Open Knowledge Format compatibility

Part of Architecture. how the store's metadata aligns with OKF.

Open Knowledge Format (OKF) Compatibility

Shipped 2026-06-22 (PR #195). demarkus aligns its document content model with Google's Open Knowledge Format v0.1. Scoped to two layers, deliberately:

• Document level: compatible. Recognized OKF fields (type, title, description, resource, tags, timestamp) serialize as bare store frontmatter under their OKF names; tags as a YAML flow list. Non-spec publisher keys keep the meta. prefix. Store-operational fields (version, previous-hash, archived) are reserved and enforced by name (a reservedMetaKeys denylist replaced the old "meta. prefix as the integrity boundary" mechanism; see ADR 0002). The in-memory metadata map stays bare-keyed, so only buildVersionFile (write) and extractMetadata (read) changed; catalog/handler/filter were untouched.
• System level: superset. Versioning, hash chain, QUIC, capability auth, and LOOKUP wrap an OKF-compatible document. Not a bundle server: frontmatter is stripped before serving and versions/ is not a bundle tree. Bundle interop is the out-of-band demarkus okf codec (client/internal/okf): validate / import / export, verified byte-identical body round-trip.

Default type on write. The server assigns type: Document (protocol.OKFDefaultType) on PUBLISH and APPEND when none is declared (index.md/log.md exempt), so every served document is a typed OKF concept by construction. ADR 0003.

Metadata caps (supersedes the maxStoreFrontmatter = 256 figure in the Size Limits section above). OKF producer-defined fields drove these up: MaxMetaKeys 10→50, MaxMetaBytes 512→1024, maxStoreFrontmatter 256→2048. MaxMetaBytes is the binding limit (sum of key+value lengths), not key count. Subtlety: tags is validated as a csv string ("a,b") but stored as a longer YAML flow list ([a, b]), so the byte cap is enforced via store.SerializedMetaSize (counts the on-disk serialized length) in BOTH the store validateMeta and the handler size check; one source of truth, so the 2048 frontmatter budget is a provable on-disk bound (worst case ~1542 < 2048).

See SPEC §8.1/§9.4/§13/§14, ADR 0002 (metadata alignment), ADR 0003 (default type).