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. §5.2's verified stamps are written by BundleConceptWriter.RecordVerifications, the single governed writer behind okf verify and okf_verify. |
| §5.3–§5.5 trust, lifecycle, staleness | ConceptAudit, AuditQuery, AuditReport — the corpus-level query behind okf audit and okf_audit: counts for the whole bundle, plus a filterable worklist. |
| §6 Cross-linking and paths | LinkScanner, Bundle.LinksFrom/Backlinks — absolute or relative markdown links; broken links tolerated. |
| §6.2 Path-valued fields | OkfDocument.FrontmatterResources(), Bundle.TryResolveResource/ReadResourceText — the path-valued fields (resource, each sources[i].resource, and §10.2's computation, executor.resource, attester.resource), resolved from the bundle root and refused if they would leave it. |
| §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). The contracts it plugs now have a container-based implementation in the repository — see agents.md. |
| §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 pins the CLI's rendering with snapshots of this project's own output (regenerable under the regimes in tests/fixtures/README.md) and its machine outputs with full-projection tests against hand-derived expectations; the spec is the only conformance authority. 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 ↗