The format is short. Each spec section maps to one OKF4net type — parse failures never abort a load, unknown keys and broken links are tolerated, and exactly one thing is required. Here is the whole surface, cross-referenced to the upstream spec and to library.md.
Every concept must carry a non-empty type. Everything else, a consumer must tolerate.That is the entire conformance bar. Unknown types, unknown frontmatter keys, broken cross-links, and missing optional fields are all valid — a conformant consumer keeps going and reports, never rejects. OKF4net enforces exactly this in BundleValidator (§11) and, per document, in OkfDocument.ValidateConformance(); the stricter producer check (type, title, description, timestamp) is a separate, opt-in Validate().
v0.2 is a superset of v0.1: every v0.1 bundle keeps loading and validating unchanged. What's new is entirely additive, plus two sanctioned legacy fallbacks (§13.1) for the fields it supersedes:
sources (per-source credibility signals), generated/verified stamps deriving a trust tier (unverified / machine-confirmed / human-reviewed), and status/stale_after for lifecycle.human:<id>, process:<id>, or <producer>/<version> — trust classification keys off the human: prefix.timestamp is superseded by generated.at (a bare timestamp is still read when generated is absent); the body # Citations list is superseded by frontmatter sources (still parsed as a fallback for v0.1 documents).Frontmatter.ComputationContract) and a sanctioned computation — an inline fenced # Computation heading or a computation: file resolved via §6.2 path-safe resolution (OkfDocument.Computation()). The new zero-dependency OKF4net.Attestation package hosts the bind → execute → attest orchestration; see agents.md for the agent-facing tools.| Section | Implemented by |
|---|---|
| §2 Terminology | ConceptId — bundle, concept, and the concept id (a file path with .md removed). |
| §3 Bundle structure | Bundle — a directory tree of UTF-8 markdown; index.md/log.md reserved. |
| §4 Concept documents | OkfDocument, Frontmatter — YAML frontmatter delimited by ---, then a markdown body. |
| §5 Provenance, trust, and lifecycle | Frontmatter.Sources/Generated/Verified/TrustTier/Status/StaleAfter, and the Actor/Trust/Provenance/Lifecycle value types. |
| §6 Cross-linking and paths | LinkScanner, Bundle.LinksFrom/Backlinks — absolute or relative markdown links; broken links tolerated. |
| §7 Actor convention | Actor.Parse — human:/process:/<producer>/<version>. |
| §8 Index files | IndexGenerator — index.md directory listings for progressive disclosure. |
| §9 Log files | ChangeLog — log.md date-grouped change history. |
| §10 Attested computations | Frontmatter.ComputationContract, OkfDocument.Computation() — shipped in 0.3.1-preview.1 alongside the host-plugged OKF4net.Attestation orchestrator (bind → execute → attest → stale-gate). |
| §11 Conformance | BundleValidator, OkfDocument.ValidateConformance() — the one hard rule above. |
| §12 Versioning | Bundle.OkfVersion, OkfSpec.Version — optional okf_version declaration. |
| §13 Changes from v0.1 | Frontmatter.LastChangedAt (falls back to legacy timestamp), OkfDocument.Sources() (falls back to a legacy # Citations list) — see "What's new in v0.2" above. |
Two filenames are structural, not concepts: index.md (generated listings) and log.md (change history). OKF4net surfaces them separately — Bundle.IndexFiles and Bundle.LogFiles — and neither counts toward Bundle.Count. Regenerate indexes with IndexGenerator.RegenerateIndexes; parse a log with ChangeLog.Parse. A malformed reserved file (bad structure, or unreadable/unparseable) is a §11 conformance failure — okf validate exits 1, not a silent warning.
Behaviour conforms to the OKF v0.2 spec. The document parser, validator, and index generator are an independent implementation of it — not a port of Google's own reference implementation, whose CLI covers a different surface entirely (BigQuery/Gemini bundle enrichment and Cytoscape.js visualization, not validate/info/graph/fmt/index). The suite's byte-exact golden CLI comparisons mostly trace to this project's own former Rust implementation, before its removal; the newer v0.2 and §10 behaviour predates any reference implementation and is hand-verified against the spec text instead. Any intentional divergence from the spec is documented with its reason; there are none that affect conformance.
Bundle.Load collects parse failures in ParseErrors and retains broken links as graph edges to missing concepts — §11's tolerance, made structural.|/> — anchors, tags, and multi-document streams are rejected with a clear error, since frontmatter never uses them.# Citations fallback is what used to be v0.1's §8 — superseded by frontmatter sources (§5.1); a references/ subdirectory (§6.3) is a naming convention for external material, not a requirement.→ library.md — the types up close · the upstream spec ↗