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.2 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, including the §10 attested-computations concept — see the spec mapping.
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.
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 §11 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 Provenance, trust, and lifecycle | Frontmatter.Sources/Generated/Verified/TrustTier/Status/StaleAfter, and the OKF4net.Actor/Trust/Provenance/Lifecycle value types |
| §6 Cross-linking | OKF4net.LinkScanner, Bundle.LinksFrom / Bundle.Backlinks |
| §7 Actor convention | OKF4net.Actor.Parse — human:/process:/<producer>/<version> |
| §8 Index files | OKF4net.IndexGenerator |
| §9 Log files | OKF4net.ChangeLog |
| §10 Attested computations | Frontmatter.ComputationContract, OkfDocument.Computation(), OKF4net.Attestation |
| §11 Conformance | OKF4net.BundleValidator |
| §12 Versioning | Bundle.OkfVersion, OKF4net.OkfSpec.Version |
| §13.1 Citations (legacy fallback) | LinkScanner, OkfDocument.Citations() |
→ library.md — how to use those types, with examples