insight
What the Open Knowledge Format does
Answer first
A directory of markdown files with YAML frontmatter, published by Google Cloud as an open specification. What OKF requires, what its trust fields record, and which of your problems it leaves untouched.
Google Cloud announced version 0.1 of the Open Knowledge Format on 12 June 2026, in a post on the Google Cloud blog titled "How the Open Knowledge Format can improve data sharing", and shipped version 0.2 roughly six weeks later. It is an open specification, Apache-2.0, in the GoogleCloudPlatform/knowledge-catalog repository, and it describes one thing: how to lay out a directory of markdown files so that an agent can walk it without a bespoke SDK and a person can read it without any tooling at all. Both the announcement and the specification are linked at the foot of this article.
The interesting part is not the file layout. It is what version 0.2 added on top of it, and what that addition tells you about the problem Google thinks its customers now have.
What the specification actually requires
A bundle is a directory tree. Each concept is one markdown file with a YAML frontmatter block, and the concept's identifier is its path within the bundle with the .md suffix removed. Two filenames are reserved: index.md lists what a directory contains, so an agent can descend the tree progressively rather than loading everything, and log.md records changes newest first.
Conformance is three rules. Every non-reserved markdown file has parseable frontmatter, every frontmatter block has a non-empty type field, and the two reserved files follow their prescribed structure when present. That is the whole of it. Everything else in the specification is guidance.
The obligations placed on consumers are more revealing. A consumer must not reject a bundle for missing optional fields, unknown type values, unknown frontmatter keys, broken cross-links, or absent index files. The format is designed on the assumption that bundles will be incomplete, inconsistent, and partially broken, because they are written by agents at a rate no review process can keep up with.
The fields version 0.2 added
Version 0.1 standardised identity: type, title, description, resource, tags. Version 0.2 answers a different set of questions, and the specification states them plainly: what was this created from, how much should I trust it, is it still true, and was this number produced the way we said it must be.
| Family | Fields | What it records |
|---|---|---|
| Identity | type, title, description, resource, tags | What the concept is and where the real asset lives. Only type is required. |
| Provenance | sources, usage_window | The materials a concept derives from, with per-source credibility signals: author, usage_count, last_modified. |
| Trust | generated, verified | Who produced the content and when, and a list of verification events, each with an actor and a timestamp. |
| Lifecycle | status, stale_after | Draft, stable or deprecated, and an absolute date after which the content is considered stale. |
| Attestation | runtime, parameters, computation, executor, attester | For an Attested Computation: the sanctioned way to compute a value, so a consumer can confirm a number was produced by running it. |
Actors follow a convention that carries the weight of the trust model: producer/version for an agent, human:id for a person, process:id for an automated process. From the verified field a consumer derives a trust tier. No verified key means unverified. Verification by non-human actors only means machine-confirmed. Verification by a human: actor means human-reviewed.
That is a sensible piece of design, and it is worth being precise about what it gives you. The tier is derived from a claim written into a file by whoever or whatever wrote the file. OKF records the assertion and standardises how it is expressed. Enforcing it — deciding who may write human:ahormati into a frontmatter block, and on what evidence — belongs to the pipeline that produces the bundle, and the specification says so by leaving it out.
Where it sits against what you already run
OKF is a format for knowledge at rest. It is not a protocol, not a registry, and not a runtime, and the specification's non-goals are unusually clear about the boundary.
- A metadata catalogue holds the same material behind a proprietary API. OKF is what that catalogue can export so the contents survive the catalogue.
- MCP is how an agent reaches a live tool or data source at request time. OKF is what the agent reads to know what those sources mean. The two answer different questions and compose without overlapping.
- llms.txt tells a crawler which pages matter on a website. OKF describes concepts inside an organisation, most of which have no public URL.
- Avro, Protobuf and OpenAPI keep their jobs. The specification states explicitly that OKF references domain schemas rather than subsuming them.
- A git repository is the intended distribution channel. A bundle is a directory, so it diffs, reviews and reverts like code.
What it leaves to you
Four things, each of which is where the engineering effort in a real deployment goes.
Access control. A bundle is a directory of files, and whoever can read the directory can read every concept in it. If a fragment of your knowledge base describes a table only the finance team may know exists, that constraint has to be enforced by the store serving the bundle and by the retrieval layer above it. What that costs is the subject of retrieval that respects access control, and nothing in OKF changes it.
Correctness. The trust family records who verified a concept and when. Whether the description of a column is accurate is a question about your review process.
Currency. stale_after is a date the producer writes down. Something has to notice the date has passed and act on it, and that something is a job you schedule, not a feature of the format.
Retrieval. index.md supports progressive disclosure by an agent walking the tree, which works well at a few hundred concepts. Beyond that you are building an index over the bundle, and the format neither helps nor hinders.
The value of OKF is that a knowledge base stops being a feature of the tool that stores it. Everything that made the knowledge base hard is still hard.
When it is worth emitting
The case is strongest where knowledge crosses a boundary. Between one team's catalogue and another team's agent. Between a vendor platform and the organisation that will still need the material after the contract ends. Between an agent that writes documentation and the four systems that read it.
It is weakest where a single tool holds the knowledge and a single tool consumes it. There the export is an extra artifact to keep synchronised, and a stale bundle is worse than no bundle, because a consumer has no way to tell it is stale beyond a stale_after date the producer may not have set.
Adoption is early. The specification is at 0.2, the reference producer and consumer that ship alongside it are proofs of concept, and no consumer crawls OKF bundles at scale today. That argues for generating a bundle from a system you already maintain, rather than authoring one by hand as a new source of truth.
What we recommend
- Emit, do not author. Generate the bundle from the catalogue, warehouse or repository that already holds the material, and regenerate it on a schedule. A hand-written bundle becomes a second system of record within a quarter.
- Set type deliberately. It is the only required field and the only thing a consumer can group on. An ad hoc vocabulary here is the one decision that is expensive to reverse later.
- Treat verified as a workflow, not a field. Decide what a human: verification means in your organisation, and let only the pipeline that performs that check write it.
- Review bundles as code. Pull requests, ownership, and the same standard you apply to a schema change. The format is built for it.
- Keep expectations proportionate to 0.2. The exit cost is a directory of markdown you can delete, which is the main reason it is a reasonable bet this early.
The reason to pay attention is not that Google published a specification. It is that the specification's motivating question — how much should I trust a document an agent wrote — is now a first-class field in a file format. That question is arriving in every organisation running agents against its own material, whether or not OKF turns out to be the format that answers it.
- What is the Open Knowledge Format?
- An open specification, published by Google Cloud in June 2026 and licensed Apache-2.0, for representing a knowledge base as a directory of markdown files with YAML frontmatter. Each file describes one concept. The only required frontmatter field is type; index.md and log.md are reserved for directory listings and change history.
- How does OKF relate to MCP?
- They solve different problems and compose. MCP is a protocol for an agent to reach a live tool or data source at request time. OKF is a format for the curated knowledge an agent reads to understand what those sources mean. An organisation can use both, and neither depends on the other.
- Does OKF handle access control?
- No. A bundle is a directory of files, and anyone who can read the directory can read every concept in it. Permission enforcement belongs to the store that serves the bundle and the retrieval layer above it. The specification is explicit that serving and query infrastructure are out of scope.
- What does the verified field guarantee?
- It records that a named actor confirmed a concept at a given time, and consumers derive a trust tier from it: unverified, machine-confirmed, or human-reviewed. It is an assertion written into the file by the producer. Whether the assertion is trustworthy depends on the pipeline that writes it, which OKF deliberately leaves undefined.
- Is OKF ready to adopt in production?
- As an export format, yes, because the cost of being wrong is a directory of markdown files in git. As the primary system of record, not yet. The specification is at version 0.2, the reference producer and consumer are proofs of concept, and no consumer reads OKF bundles at scale today.
- How the Open Knowledge Format can improve data sharing — Google Cloud Blog
- Open Knowledge Format v0.2 core specification — GoogleCloudPlatform/knowledge-catalog
- LLM wiki — Andrej Karpathy
Newsletter
Occasional notes on building systems that hold up
A short email when we publish something worth your time. Architecture, integration, and operational AI in regulated organizations. No cadence promises, no forwarding your address.