How to Build an OKF Bundle: A Step-by-Step Guide to Google's Open Knowledge Format

This guide assumes the "why" from OKF vs RAG — that Google's Open Knowledge Format (OKF) solves deterministic lookup of known facts, not fuzzy retrieval — and focuses entirely on the "how." If you haven't decided whether OKF is the right tool for what you're building, start there first.

An OKF bundle is nothing more than a directory of markdown files. Here's a small, real one for a payments team's on-call knowledge, the kind of thing that would otherwise live scattered across a wiki, a runbook doc, and someone's memory:

Two file names are reserved: index.md (a directory listing, for progressive disclosure) and log.md (update history for that scope). Every other markdown file is a concept — one knowledge artifact per file. The rest of this guide builds the two concept files above from nothing to spec-conformant.

Per the spec's conformance criteria, a concept file needs exactly one thing: a YAML frontmatter block with a non-empty type field. This is, in full, a valid OKF concept:

That's conformant. It's also nearly useless to anyone reading it. The recommended fields exist precisely to close that gap — title, description, resource, and tags are all optional per the spec, but they're what make a concept worth an agent's or a human's time to open:

Nothing here requires a schema registry or a Google Cloud account to write or validate. It renders correctly on GitHub as-is, and any consumer that can read a file and parse YAML frontmatter can use it.

The spec moved from v0.1 to v0.2 within months of its initial release, and the additions are specifically the trust and lifecycle fields v0.1 didn't have — this is the part of the spec that's easiest to find outdated coverage of, because most of what's been written about OKF still describes v0.1.

Five fields matter here, all optional, all worth using on concepts where an agent needs to judge freshness or trust before treating something as ground truth:

• `status` — one of draft, stable, or deprecated. An agent reading a deprecated runbook should say so, not follow it silently.
• `stale_after` — an absolute YYYY-MM-DD date. Past this date, the concept is a candidate for review, not automatically wrong — the spec doesn't mandate any behavior on expiry, it just gives a consumer the date to reason about.
• `generated` — a { by, at } object recording who or what produced the file and when.
• `verified` — a list of { by, at } entries; a bare mapping (not wrapped in a list) is explicitly valid too, since the spec requires consumers to treat a single verified entry as a one-element list rather than rejecting it.
• `sources` — an array of credibility signals (author, usage_count, last_modified) an agent can weigh when a concept was assembled from more than one place.

Applied to the runbook:

None of this is required to be spec-conformant. It's the difference between an agent that can only say *what* a runbook claims and one that can also say *how much to trust it right now*.

Nothing so far turns this into more than a pile of markdown files sitting next to each other. What makes it a graph is concepts referencing each other with plain links. The metric concept can point at the runbook that explains what to do when it spikes:

That link is a real, traversable edge in the concept graph, not a comment an agent has to guess the meaning of. And per the conformance rules, a link whose target doesn't exist yet is not malformed — you can write the reference before the file exists and add it later without breaking anything that reads the bundle in the meantime.

index.md and log.md are both optional, and consumers must not reject a bundle for missing them. Add index.md once a directory has enough concepts that a flat listing genuinely helps navigation — it's progressive disclosure, not a manifest every consumer depends on. Add log.md when you want a chronological record of what changed in that scope, useful for an agent (or a human) asking "what's new here since I last looked," a question a plain directory listing can't answer on its own.

Almost every conformance requirement in the spec is aimed at *consumers* — tolerate unknown types, tolerate missing optional fields, tolerate broken links, tolerate a missing index.md. The one requirement aimed at *producers* is the type field. A minimal validator only needs to check that:

This deliberately checks nothing else — no schema on type values, no requirement that links resolve, no requirement that recommended fields exist — because a stricter check would itself be non-conformant with what the spec requires consumers to tolerate. Google's own repository ships a more thorough reference agent alongside the spec, but it targets BigQuery and Gemini specifically; this check works on any bundle, from any source, with zero dependencies.

The hybrid-architecture point from the companion post becomes concrete here: an agent needs two different tools, not one retrieval pipeline that tries to serve both.

Direct lookup, for when the agent already knows what it's asking for — a table schema, a specific runbook:

Graph walk, for when the agent is exploring — "what do we know about payments incidents":

Neither of these is a similarity search, and that's the point: there's nothing to rank. The agent asked for payments/runbooks/stripe_webhook_outage.md and got exactly that file, with a status and stale_after it can reason about before trusting it. Everything genuinely unstructured — support tickets, chat logs, freeform docs — keeps going through whatever RAG pipeline you already have. This bundle doesn't replace it; it just stops those two problems from being solved with the same tool.