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 (§9) and, per document, in OkfDocument.ValidateConformance(); the stricter producer check (type, title, description, timestamp) is a separate, opt-in Validate().
| Section | What it defines | Implemented by |
|---|---|---|
| §2 Terminology | Bundle, concept, and the concept id — a file path with .md removed (tables/users.md → tables/users). | ConceptId |
| §3 Bundle structure | A directory tree of UTF-8 markdown; index.md and log.md are reserved filenames. | Bundle |
| §4 Concept documents | A concept: YAML frontmatter delimited by ---, then a markdown body. Reserved keys include type, title, description, timestamp, resource, tags. | OkfDocument, Frontmatter |
| §5 Cross-linking | Ordinary markdown links between concepts — absolute (/tables/users.md, bundle-relative) or relative (./other.md). Backlinks are derived. | LinkScanner, Bundle.LinksFrom / Backlinks |
| §6 Index files | index.md directory listings for progressive disclosure. | IndexGenerator |
| §7 Log files | log.md date-grouped change history. | ChangeLog |
| §8 Citations | Numbered [n] citations within a body. | LinkScanner, OkfDocument.Citations() |
| §9 Conformance | The one rule above, with severity-tagged diagnostics. | BundleValidator |
| §11 Versioning | An optional okf_version declaring the spec version a bundle targets. | Bundle.OkfVersion, OkfSpec.Version |
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.
Behaviour conforms to OKF v0.1. The document parser, validator, and index generator are faithful ports of the reference implementation — verified by tests adapted from the reference suite and, for the CLI, by byte-exact comparison against captured reference output. Any intentional divergence 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 — §9's tolerance, made structural.|/> — anchors, tags, and multi-document streams are rejected with a clear error, since frontmatter never uses them.→ library.md — the types up close · the upstream spec ↗