Consumers that filter to current knowledge follow the pointer and return the replacement. The same mechanism handles moves and renames. Leave a short deprecated concept at the old path that points to the new one, and existing links and stored references keep working.
One rule for links and paths
Links in the body and path fields in frontmatter (resource, superseded_by, executor.resource, and others) now resolve the same way:
-
A value with a scheme (https:) is an absolute URL.
-
A value that starts with / resolves from the bundle root.
-
Anything else resolves from the directory of the file that contains it, just like on GitHub or in any markdown editor.
For bundles marked v0.2 or earlier, or with no version, a consumer can also resolve paths from the bundle root, so existing bundles keep working.
v0.3 also makes explicit that links are not parent/child relationships. Only the directory tree defines hierarchy. A link is an untyped, directed relationship, and the text around it says what kind (“joins with,” “replaces,” “depends on”). Path fields that point at concepts are edges in the bundle graph too.
Room to extend, without collisions
The community has been extending OKF since v0.1, with typed edges, routing hints, and erasure profiles. v0.3 makes a few extension mechanisms a first-class rule:
-
Extension keys are allowed at any level, including inside sources entries, verified events, executor, and attester.
-
A producer that edits a file must keep the keys it doesn’t understand so one tool doesn’t overwrite metadata added by another.
-
Future OKF versions will never define keys that start with x-. Name your keys x–, for example x-acme-owner, and they won’t collide with a future spec version.
A versioning policy before 1.0
v0.3 defines OKF’s versioning rules. 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.
The spec also lists what was considered and deferred: typed relationships, the full attestation runtime protocol (receipt and verdict wire formats), semantic-layer attestation, validity windows, and a refuted verification event. Until the community agrees on a form for these, extension keys are the place to experiment. We’d like your proposals.
Introducing OKF use cases
OKF keeps its core specification small and links to existing domain schemas like Avro, Protobuf, or OpenAPI instead of duplicating them. In practice, though, when your organization already has an established artifact in another standard, such as a schema, a contract, or a spec, what should the OKF concept next to it say, and how should an agent use the two together?
Starting with v0.3, we’re publishing use cases: guides for using OKF with other industry standards. Each one explains:
-
Where the boundary sits: what belongs in the other standard and what belongs in OKF.
-
How to link the two: which frontmatter and link conventions point from a concept into the other artifact.
-
What an agent should do with the combination.
-
A complete worked example you can copy.
Use cases are layered on the core spec, not part of it. A bundle that ignores them is still a conformant OKF bundle. When a convention proves itself across several use cases, it can be proposed for the core spec through the usual process.
Use cases are managed directly in GitHub. Each use case gets its own folder under usecases/ in the OKF repository, for example usecases//. The guide is a .md file in that folder, and any sample bundles or artifacts sit next to it. Use cases are reviewed, versioned, and discussed like any other change.
Propose a use case
If you pair OKF with a standard, please send us a proposal. A rough first draft is welcome. Open a pull request that adds a folder under usecases/ with a .md file in it, and we’ll refine it together in review.
Compatibility
v0.3 has two breaking changes, and existing v0.2 bundles stay readable:
-
Path fields resolve relative to their file. Fallback: for bundles marked v0.2 or earlier, or with no version, consumers can resolve from the bundle root.
-
Only current verifications count toward the trust tier. No fallback needed, since tiers can only go down.
Everything else is a clarification or an optional addition. v0.1 fallbacks (timestamp, body # Citations) still apply.
Agent skills for OKF
The two skills live in the new repository and follow the open Agent Skills format, so any agent that supports skills can load them.
-
okf-generate writes, updates, migrates, and validates bundles from available sources. It cites a source for each claim, records a human review only when that person confirms it, and copies attested computations from a sanctioned source instead of writing them.
-
okf-consume answers questions from a bundle. For each concept used, it reports the trust tier, status, freshness, and attestation result, and runs attested computations only through the bundle’s configured executor and attester.
To install them in Gemini CLI, run:






