OKF v0.3 Adds Conformance, Trust Tiers, and Bundle Lifecycle

The Open Knowledge Format (OKF) is an open specification that uses plain markdown and YAML to give agents the context they need. Released today, OKF v0.3 builds on the June launch and the July v0.2 trust-signal additions with precise conformance rules, trust tiers that track agent edits, self-describing bundles, safer knowledge retirement and moves, a stable extension model, and a clear versioning policy. The core idea remains the same: type is still the only required field, and existing bundles keep working.

v0.3 adds a formal conformance section using RFC 2119 keywords so independent producers and consumers can interoperate by design. The spec stays small and standard-based: YAML 1.2 frontmatter, CommonMark with GFM tables and footnotes, and RFC 3339 timestamps. A .md file without a type is skipped by OKF consumers, so README.md, AGENTS.md, CONTRIBUTING.md, and SKILL.md can live inside a bundle without breaking it. Non-markdown files are treated as assets that concepts can link to. The spec also defines how consumers handle real-world agent-produced input such as nulls, empty strings, single values where a list was expected, and new vocabulary: consumers accept these without failing, while validators log warnings. A bundle never fails because an optional field is missing or a link is broken.

Trust tiers now reflect the latest version of content. v0.2 introduced unverified, machine-confirmed, and human-reviewed tiers; v0.3 specifies that only current verifications count. A verification is current when it happened at or after the last meaningful change recorded in generated.at. If an agent refines a definition after a human signed off, the concept becomes machine-confirmed until that person confirms it again. The older sign-off stays in the file as history. Actor identifiers are standardized as / for tools and : for everything else, with team: added alongside human: and process:. Only human: earns human-reviewed, since a team name does not indicate which person actually checked the content.

Bundles become self-describing. The bundle-root index.md can carry frontmatter about the bundle itself: description for routing, license for reuse rights, and okf_version to tell consumers which rules to apply, including compatibility fallbacks for older bundles. Tools that regenerate index.md must preserve this frontmatter. Knowledge retirement is handled with superseded_by: a deprecated concept points to its replacement, and consumers filtering to current knowledge follow the pointer. This also covers moves and renames by leaving a short deprecated concept at the old path. Links in the body and path fields in frontmatter now resolve the same way: values with a scheme are absolute URLs, values starting with / resolve from the bundle root, and anything else resolves from the directory of the containing file. For bundles marked v0.2 or earlier, consumers can still resolve from the bundle root. Links are explicitly not parent/child relationships; only the directory tree defines hierarchy.

Extension is formalized. Extension keys are allowed at any level, including inside sources entries, verified events, executor, and attester. A producer editing a file must keep keys it does not understand so one tool does not overwrite another tool’s metadata. Future OKF versions will never define keys starting with x-, so names like x-acme-owner are collision-safe. The versioning policy states that before 1.0, minor versions may include breaking changes as long as each is documented with a consumer fallback where possible. Starting at 1.0, minor versions will be strictly additive, and released normative text will not change in place. Deferred items include typed relationships, the full attestation runtime protocol, semantic-layer attestation, validity windows, and a refuted verification event; extension keys are the place to experiment.

OKF use cases are now available as community guides for pairing OKF with other industry standards such as Avro, Protobuf, or OpenAPI. Each use case explains the boundary between the other standard and OKF, how to link the two, what an agent should do with the combination, and includes a complete worked example. Use cases are layered on the core spec, not part of it; a bundle that ignores them is still conformant. They live in their own folders under usecases/ in the repository and are reviewed, versioned, and discussed like any other change. Proposals are accepted as pull requests adding a folder with a .md file.

v0.3 has two breaking changes, and existing v0.2 bundles stay readable. Path fields now resolve relative to their file, with a fallback for v0.2-or-earlier or unversioned bundles. Only current verifications count toward the trust tier, with no fallback needed since tiers can only go down. v0.1 fallbacks still apply. Two agent skills are included in the new repository: okf-generate writes, updates, migrates, and validates bundles while citing sources and recording human review only on confirmation; okf-consume answers questions from a bundle and reports trust tier, status, freshness, and attestation results, running attested computations only through the configured executor and attester. The project has moved to a standalone GitHub organization at https://github.com/open-knowledge-format/open-knowledge-format/.

Introducing OKF v0.3

View Original