bundle
A directory tree of UTF-8 markdown files — the unit of distribution. Ship it with git clone, read it with cat.
The Open Knowledge Format v0.1 is Google's open, human- and agent-friendly format for representing knowledge as a directory of markdown files with YAML frontmatter. It is intentionally minimal — and OKF4net implements all of it.
A directory tree of UTF-8 markdown files — the unit of distribution. Ship it with git clone, read it with cat.
One markdown document: a YAML frontmatter block delimited by ---, followed by a markdown body.
The file's path within the bundle with .md removed: tables/users.md → tables/users.
Concepts link via ordinary markdown links — absolute (/tables/users.md, bundle-relative) or relative (./other.md). Backlinks are derived.
Two filenames are reserved in every directory of a bundle:
index.md — a generated directory listing, for progressive disclosure: an agent (or a human) reads the index first and descends only into what looks relevant.log.md — a date-grouped change history for the directory's concepts.OKF4net generates both: IndexGenerator (re)builds every index.md, ChangeLog parses and builds log.md histories — verified byte-exact against the reference implementation's output.
A concept is conformant if it has a non-empty type. That's it.Everything else is deliberately permissive: consumers must tolerate unknown types, unknown frontmatter keys, broken links, and missing optional fields. This is what lets independently produced bundles interoperate.
OKF4net honors both sides of that bargain. OkfDocument.ValidateConformance() enforces only the §9 rule; OkfDocument.Validate() matches the stricter producer-side check from the reference agent (type, title, description, timestamp). And Bundle.Load never aborts on a bad file — it collects parse failures and keeps going.
The library mirrors the spec's structure, so a spec citation in an issue or a PR points straight at the responsible type:
| Spec section | Implemented by |
|---|---|
| §2 Terminology / concept id | OKF4net.ConceptId |
| §3 Bundle structure | OKF4net.Bundle, Bundle.ReservedFilenames |
| §4 Concept documents | OKF4net.OkfDocument, OKF4net.Frontmatter |
| §5 Cross-linking | OKF4net.LinkScanner, Bundle.LinksFrom / Bundle.Backlinks |
| §6 Index files | OKF4net.IndexGenerator |
| §7 Log files | OKF4net.ChangeLog |
| §8 Citations | LinkScanner, OkfDocument.Citations() |
| §9 Conformance | OKF4net.BundleValidator |
| §11 Versioning | Bundle.OkfVersion, OKF4net.OkfSpec.Version |
→ library.md — how to use those types, with examples