Google's Open Knowledge Format (OKF) explained for documentation leaders

Table of contents

• The problem OKF is solving
• Why not just frontmatter?
• The bundle as a navigable file tree
• How OKF works
• What OKF is not
• How OKF compares to llms.txt and your docs site
• Is it worth doing?
• Conclusion
• Additional resources

Your docs site works. Your AI assistant still gives bad answers. And now there is a Google spec in your feed called the Open Knowledge Format. Here is the short version: OKF represents organizational knowledge as a directory of markdown files with YAML frontmatter, and it gives agents and humans a shared, consistent way to read it without a proprietary runtime in the middle. Google shipped it from its Data Cloud organization, and its own examples are warehouse tables and metric definitions. Applying OKF to product documentation is our extension of that idea, not Google’s stated intent, and this post will be clear about that distinction throughout. What follows is the decision framing: what OKF is, what it is not, and whether you should do anything about it before the next sprint. For the broader argument that structuring documentation for AI agents and for human readers is the same discipline and not a trade-off, start with the pillar this post sits under.

The problem OKF is solving

The knowledge an agent needs to answer a question well, whether that is a metric’s definition, a join path, a deprecation notice, or a runbook, sits scattered across data catalogs, wikis, shared drives, code comments, and a few senior engineers’ heads. Every team that builds an AI assistant over that knowledge re-solves the same assembly problem from scratch. Google’s framing is that the answer is a format, not another service. OKF defines a small set of conventions so that a bundle produced by one team or tool can be consumed by any agent, editor, or visualizer without a bespoke translation layer in between.

Why not just frontmatter?

This is the first objection most documentation owners raise, and it is worth taking seriously.

Existing frontmatter is universal and inconsistent at the same time. sidebar_position in Docusaurus, weight in Hugo, nav_order in Just the Docs: all three encode the same intent in incompatible dialects. Any consumer of that metadata has to be written per-repo. There is no shared contract.

That frontmatter is written for the renderer, not the reader. It rarely answers the questions an agent needs to ask: what is this concept, where did this information come from, and when does it stop being true? A sidebar position tells a browser how to display a page. It tells an agent almost nothing about the page’s meaning.

OKF’s contribution is a contract, not more fields. One required field (type), the file path as stable, canonical identity, two reserved filenames that mean the same thing everywhere, and ordinary markdown links treated as graph edges the agent follows. Because link resolution is just path resolution, a link from one concept file to another is a declared relationship the agent can traverse deliberately rather than inferring from folder structure alone. The spec defines the interoperability surface, not the content model, and there is no central type registry.

The payoff is producer and consumer independence. A hand-written bundle, a pipeline export, or a model-generated corpus can all be read by any agent or tooling that understands OKF, because the format is the contract and the tooling at both ends is swappable. This is the same promise DITA made for structured XML, applied to markdown with a much smaller surface area.

The bundle as a navigable file tree

Think of an OKF bundle as a self-contained directory tree the agent treats as a navigable file library, not a database. It is shippable as a git repo, a tarball, or a subdirectory. Nothing about it requires a server.

my-knowledge-bundle/
  index.md              ← root directory listing
  metrics/
    index.md            ← topic-level directory listing
    daily-active-users.md
    revenue-recognition.md
  runbooks/
    index.md
    deploy-rollback.md

The agent does not load the whole corpus. It reads the index.md at the root, finds the branch that covers the topic it needs, and descends into that branch, following markdown links deeper the way a person clicks through a wiki. Because each link is just a relative path, traversal is deliberate rather than a guess. index.md and log.md are both optional reserved filenames: index.md acts as the directory listing at each level, and log.md holds a chronological change history for the bundle. Think of this as your sidebars.js, except it lives inside the content, so it travels with the corpus when it leaves the site.

How OKF works

The rules are deliberately minimal:

• A bundle is a directory. A concept is a markdown file.
• The concept’s ID is its file path with .md removed.
• Frontmatter holds queryable fields. The body is ordinary markdown.
• Links form a graph richer than the folder tree alone.
• type is the only required field. Everything else is left to the producer.

A minimal concept file looks like this:

---
type: metric
title: Daily active users
status: stable
stale_after: 2026-12-01
---
The count of unique users who performed at least one session in a calendar day.

v0.2 makes trust and freshness first-class. When agents write thousands of concepts, the implicit accountability of a human-maintained wiki disappears. OKF v0.2 moves the “should I trust this?” signals into frontmatter: sources for provenance, generated and verified as trust tiers, and status plus stale_after for freshness. For a documentation team, these map directly onto review dates and deprecation workflows, the same structural hygiene covered in detail in why your AI support bot gives wrong answers. Note that v0.2 renamed two v0.1 fields: timestamp became generated.at, and sources supersedes the earlier provenance handling. If you are looking at v0.1 references elsewhere, they are already out of date.

What OKF is not

OKF is not an SEO signal. Google’s search systems do not fetch a bundle from your domain and adjust your rankings based on it. Publishing a bundle changes nothing about your visibility in search results.

OKF is not a web-discovery file. llms.txt signals to AI systems which parts of your documentation are authoritative by pointing outward at public URLs. OKF points inward at your own agents and tooling. It is not fetched over HTTP by default, and it does not live at your site root.

OKF is not a runtime, an index, or a model. There is no SDK you call, no account to create, and no proprietary system between the agent and the files.

The “not an official Google product” line is standard open-source boilerplate, not a signal of abandonment. The spec lives in an Apache 2.0 repository inside a live Google product organization. Google frames it as a starting point, the reference agent and viewer are explicitly proofs of concept, and the format itself is the contribution. It is still v0.x and it will keep changing.

How OKF compares to llms.txt and your docs site

Layer	Who reads it	How it is consumed	Where it lives
Rendered docs site	Humans and search crawlers	Browsers, indexers	Public web
llms.txt	LLM systems	Fetched over HTTP, honoured inconsistently	Site root
OKF bundle	Agents reading files	File traversal, path resolution	Git repo or filesystem

A short note on related patterns: llms.txt is a pointer, AGENTS.md and CLAUDE.md are informal prompt patterns for agents, and OKF is the portable knowledge itself. They stack rather than compete. OKF is a second output from the same source of truth, not a replacement for the docs site, and most of the knowledge an internal agent needs was never eligible for the public site anyway. For teams already running a documentation MCP server, an OKF bundle is the lighter-weight complement: a static, versionable snapshot rather than a live query layer.

OKF and RAG are also complementary rather than competing. OKF’s single-concept, well-tagged files give a retrieval layer cleaner chunks to work with. It improves RAG rather than replacing embeddings, permissions, or evaluation. Before reaching for either, it is worth doing the structural audit your knowledge base needs before any agent-readable schema is worth adding.

Is it worth doing?

The case for moving now:

• The cost floor is near zero. OKF is markdown in git. A failed bet leaves you with a well-organised, typed corpus.
• The work it forces, naming concepts, assigning types, setting owners and staleness dates, is work a documentation team should be doing regardless of whether OKF survives.
• If you already ship docs-as-code with CI pipelines, you have most of the infrastructure.
• The honest comparison is the schema-markup bet from a decade ago: cheap to ship, and it makes your knowledge legible to the agents that field questions about you.

The case for waiting:

• v0.x, and it already changed once in roughly six weeks. v0.2 superseded v0.1 with two deliberate breaking changes.
• The spec is deliberately lenient: broken links and unknown types are tolerated, so conformance guarantees little and quality varies between bundles.
• No adoption data exists outside Google’s own reference implementations, and the consumer ecosystem is thin.
• An agent writing into your bundle from untrusted input is a real indirect prompt-injection surface. Control what is allowed to write into it.
• It will not help your public SEO.

If you decide to proceed: run a reversible pilot of 20 to 50 concepts drawn from what your existing assistant already gets wrong. Add CI validation for type presence and stale_after dates. Assign named reviewers. Take a before-and-after read on retrieval quality. Do not frame this as a migration. Treat it as a probe.

Conclusion

OKF may or may not become the format that wins. That is genuinely unknown at v0.x. But the discipline it describes, one concept per file, stable path-based identity, declared type, named owner, an expiry date, is what makes any corpus usable by a machine. Teams that build that discipline into their documentation practice are well-positioned regardless of which spec eventually dominates. It is worth noting that OKF formalizes the LLM-wiki pattern Andrej Karpathy popularized via a public gist in April 2026, which is why the idea has traction beyond Google. Two months after that gist, Google formalized the same constraints as a portable, shareable spec. The convergence is the signal.

If you want help thinking through whether an OKF pilot fits your current documentation platform and tooling, our documentation automation and tooling service is the right starting point.

---

Ready to talk through what Google’s Open Knowledge Format means for your documentation platform? Book a consult or send us a note. We help documentation teams make these decisions without the hype.

Additional resources

• OKF specification on GitHub (GoogleCloudPlatform/knowledge-catalog) — the authoritative v0.2 spec, including reserved filenames, migration notes, and the trust/provenance field definitions.
• Google Cloud blog: How the Open Knowledge Format can improve data sharing — the launch post from Google’s Data Cloud team; useful for understanding the original framing and intended use cases.
• MindStudio: What is the Open Knowledge Format? — a clear treatment of how OKF formalizes the Karpathy LLM-wiki pattern and how it sits alongside RAG.
• TinyCommand: OKF explained for AI agents — covers the prompt-injection risk and the llms.txt/OKF/AGENTS.md stack clearly.
• Wavect: Open Knowledge Format enterprise guide 2026 — detailed treatment of v0.2’s trust and provenance fields and the leniency trade-offs in the spec.