OKF v0.1 compatibility contract

Authority

The canonical authority is the Open Knowledge Format v0.1 specification at ee67a5ca27044ebe7c38385f5b6cffc2305a9c1a, observed on 2026-07-22. This document records how OKF Workbench consumes that draft specification; it does not replace it.

Bundle model

An OKF bundle is a directory tree of UTF-8 Markdown files.

• Workbench accepts no BOM or one leading UTF-8 BOM. It rejects multiple leading BOMs and rejects already-decoded text containing an unpaired UTF-16 surrogate, so text and byte inputs follow one decoding policy.
• Every non-reserved .md file whose basename has a non-empty stem is a concept, except the project-local agent integration controls described below.
• A concept ID is its bundle-relative path without .md; a provider-reported file named exactly .md cannot supply an ID and is retained as a file-scoped parse failure. Other dot-prefixed names, such as .notes.md, remain valid concepts.
• index.md and log.md are reserved at every directory level.
• A bundle root requires index.md; that root index may declare okf_version: "0.1".
• When a selected bundle is also the workspace root, Workbench excludes the root AGENTS.md and every .agents/ subtree from the bundle inventory. These paths are repository control metadata generated by the optional agent-integration workflow, not OKF concepts. A nested AGENTS.md outside .agents/ remains an eligible concept.

Workbench keeps an invalid non-reserved document in the concept and graph inventory as a partial source-backed concept. Its empty metadata/body values are recovery sentinels rather than a claim that the source conforms; the associated parse failure remains the conformance authority.

Frontmatter

For concept documents:

• YAML frontmatter is required.
• type is the only required frontmatter field.
• title, description, resource, tags, and timestamp are recommended or optional.
• Producers may add arbitrary fields.
• Consumers must tolerate unknown types and fields.

Workbench implications:

• Validation cannot use a closed enumeration of concept types.
• Write operations must preserve fields they do not understand.
• Templates are authoring presets, not schemas.
• ParsedFrontmatter.raw is always JSON-safe. Explicit standard YAML tags use the reserved shape { "$okf-workbench:yaml-tag": { "tag": <canonical tag>, "value": <JSON-safe semantic value>, "source": <original lexical value> } }. Timestamp values use an ISO string, binary values use an octet array, and sets use an ordered member array; ParsedFrontmatter.source remains the exact full-source authority. This prevents Date, Buffer, Set, or Map instances from crossing a core or Webview boundary without discarding producer intent.
• The reserved $okf-workbench:yaml-tag shape is a Workbench serialization detail, never authoritative producer syntax. ParsedFrontmatter.explicitTags records provenance obtained from the parsed YAML AST; only a real explicit tag on the field node, or an alias that resolves to that tagged node, grants explicit-tag semantics. A producer mapping or sequence that merely resembles the reserved shape remains ordinary data and cannot spoof this provenance.
• Ordinary string metadata, including an explicit-zone timestamp, keeps its existing string semantics. Supported scalar tags may supply normalized known fields, while their raw tagged representation remains available for lossless inventory and supported source-preserving writes.
• Unknown custom tags, custom runtime object prototypes, recursive aliases, and excessive alias expansion fail closed as source-scoped frontmatter failures. Mapping conversion uses null-prototype records, so producer keys such as __proto__ remain data and cannot mutate a JavaScript prototype.

Links

Internal relationships use ordinary Markdown links.

• Bundle-relative links beginning with / resolve from the bundle root.
• Relative links resolve from the source document directory.
• A link from concept A to concept B asserts a relationship.
• OKF v0.1 does not give that relationship a machine-readable type.
• Broken links are tolerated by the format.

Workbench implications:

• The graph renders internal links as directed, untyped edges.
• Broken internal links produce curation warnings, not conformance errors.
• Surrounding prose may be shown to a user but is not used to invent a semantic edge type.

Reserved files

index.md

Indexes support progressive disclosure by listing concepts and subdirectories. They normally contain no frontmatter; the bundle-root index alone may use frontmatter to declare okf_version: "0.1". The extension may synthesize missing indexes and update explicitly managed content.

log.md

Logs are optional chronological histories with ISO date headings. The MVP validates existing logs but does not automatically maintain them.

Validation levels

OKF Workbench separates two concerns:

Conformance

Whether a bundle satisfies the hard interoperability contract of OKF v0.1.

Curation

Whether a conformant bundle is easy to navigate and maintain. Examples include orphan concepts, missing recommended metadata, duplicate resources, and stale timestamps.

The Problems panel must make this distinction visible through severity and wording.

Versioning

• The initial implementation targets OKF 0.1 only.
• A standard YAML string tag such as okf_version: !!str 0.1 has the same compatibility semantics as the plain string "0.1"; its tagged raw representation remains preserved for inventory. An alias to a real !!str scalar has the same semantics because the parser retains the resolved AST provenance. A mapping, sequence, reserved-shape lookalike, or value with any explicit tag other than !!str is not a semantic-string version declaration and is rejected by compatibility gates.
• Unknown future minor versions should trigger an informational compatibility notice and best-effort reading.
• Unsupported major, malformed, and non-string version declarations remain selectable for validation and graph inspection, but existing-bundle write commands fail closed with a clear warning before planning or applying any file change.
• Automatic discovery still requires a parseable semantic-string okf_version declaration. Explicit Explorer or directory-picker selection may override discovery when the root index is missing, unreadable, versionless, or malformed so validation can publish the underlying conformance findings.
• Every existing-bundle write workflow checks the root before planning, then re-reads it after user approval and content preflight immediately before apply. A malformed, unreadable, invalid declared, or unsupported version refuses the operation without writing. A missing root index or absent declaration is not treated as an incompatible declaration: best-effort authoring remains available, and index regeneration can synthesize index.md with okf_version: "0.1". For a versionless existing root, synthesis inserts only the declaration, preserves its human body and unrelated frontmatter source, and leaves managed-region updates to the selected regeneration mode.
• Initialization is unaffected because it creates a new 0.1 bundle.
• Specification changes must be reviewed against parser, validator, templates, indexes, fixtures, and documentation.