In June we introduced the Open Knowledge Format (OKF), an open specification that provides plain markdown and YAML to give agents the context they need. In July, v0.2 added trust signals: provenance, trust, freshness, lifecycle, and attestation.
In production, bundles move between organizations, multiple agents edit the same corpus, and independent tools need to read a bundle the same way. Released today, OKF v0.3 adds precise conformance rules, trust tiers that keep pace with agent edits, self-describing bundles with licensing, safe ways to retire and move knowledge, a stable extension model, and a clear versioning policy. However, the core idea behind OKF stays the same: type is still the only required field, and your existing bundles keep working.
We’re also launching OKF use cases, which are community guides for using OKF alongside other industry standards, and two agent skills that let coding agents write and read OKF bundles. Finally, to make cross-organization collaboration easier, we’re moving OKF out of the Google Cloud Platform GitHub org into a standalone organization at https://github.com/open-knowledge-format/open-knowledge-format/.
Let’s take a closer look at what’s new in OKF v0.3.
Built for interoperability
v0.3 adds a formal conformance section, allowing independent producers and consumers to work together by design. The spec is self-contained and uses RFC 2119 keywords. It gives one clear answer to the questions that come up when tools from different teams and vendors read the same bundle. The full detail is in the spec, but a few themes matter for anyone building on OKF:
-
Built on standard file formats. OKF uses a small, widely supported set of standards: YAML 1.2 frontmatter, CommonMark with GFM tables and footnotes, and RFC 3339 timestamps. If your tools handle those, they handle OKF.
-
OKF bundles share space with other markdown files. A
.mdfile without atypeis skipped by OKF consumers, soREADME.md,AGENTS.md,CONTRIBUTING.md, andSKILL.mdcan live inside a bundle without breaking it. Files that aren’t markdown, like images or attester code, are assets that concepts can link to. -
Consumers handle real-world input predictably. Bundles written by many agents can contain nulls, empty strings, single values where a list was expected, and new vocabulary. v0.3 specifies how a consumer reads each of these. Consumers accept these inputs without failing, while validators log warnings for malformed entries. A bundle never fails because an optional field is missing or a link is broken.
Trust that keeps pace with agents
v0.2 gave every concept a trust tier: unverified, machine-confirmed, or human-reviewed. As agents take on more of the editing, v0.3 makes sure the tier always reflects the latest version of the content. Here’s a typical sequence:
-
A person reviews a metric definition and signs off.
-
A week later, an agent refines the definition.
-
The trust tier now reflects that the person hasn’t yet reviewed the new text.
In v0.3, only current verifications count. A verification is current when it happened at or after the last meaningful change to the content, recorded in generated.at:
- code_block
- <ListValue: [StructValue([('code', 'generated: { by: reference_agent/gemini-2.5-pro, at: "2026-09-02T10:00:00Z" }rnverified:rn – { by: "human:jsmith", at: "2026-08-25T09:00:00Z" } # before the rewrite: historyrn – { by: "process:finance-nightly", at: "2026-09-03T02:00:00Z" } # current'), ('language', ''), ('caption', )])]>
This concept is now machine-confirmed, not human-reviewed, until a person confirms it again. The older sign-off stays in the file as history, and a UI can show it as “reviewed before the last change.”
v0.3 also standardizes actor identifiers. Actors are / for tools, or : for everything else, and v0.3 adds team: next to human: and process:. Only human: earns human-reviewed, because a team name doesn’t say which person actually checked the content.
Bundles that describe themselves
When an agent has access to dozens of bundles, bundle-level metadata supports progressive disclosure so it can pick the right bundle without reading every file. In v0.3, the bundle-root index.md can carry frontmatter about the bundle itself:
- code_block
- <ListValue: [StructValue([('code', '—rnokf_version: "0.3"rntitle: Acme retail analyticsrndescription: Tables, metrics, and sanctioned computations for Acme retail. Use it for sales and margin questions.rnlicense: CC-BY-4.0rn—'), ('language', ''), ('caption', )])]>
-
descriptionis written for routing. In one sentence it says what the bundle covers and when to use it. -
licensemakes clear what you’re allowed to do with knowledge you receive from someone else. -
okf_versiontells a consumer which rules to apply, including compatibility fallbacks for older bundles.
Tools that regenerate index.md must keep this frontmatter.
A lifecycle with forwarding addresses
Knowledge evolves, and an agent that finds a deprecated concept should be able to get to its replacement. v0.3 adds superseded_by:
- code_block
- <ListValue: [StructValue([('code', 'status: deprecatedrnsuperseded_by: /metrics/gross-margin.md'), ('language', ''), ('caption', )])]>
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
sourcesentries,verifiedevents,executor, andattester. -
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 examplex-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:
- code_block
- <ListValue: [StructValue([('code', '# install okf-generaterngemini skills install https://github.com/open-knowledge-format/open-knowledge-format –path skills/okf-generaternrn# install okf-generaterngemini skills install https://github.com/open-knowledge-format/open-knowledge-format –path skills/okf-consume'), ('language', ''), ('caption', )])]>
The README lists the install steps for other agents.
Get involved
Read the v0.3 spec. Add okf_version to your bundles, and check that your consumer computes trust tiers from current verifications only. Issues and pull requests, including new use case proposals, are welcome on GitHub.
Spec, samples, use cases, and reference implementations: https://github.com/open-knowledge-format/open-knowledge-format/