What Is OKF? A Simple Guide to the Open Knowledge Format

(Part 1 of 5: Understanding OKF)

Here's a problem you've probably run into without having a name for it.

You're building something with an AI agent — maybe it's answering questions about your company's data, maybe it's helping run a workflow, maybe it's just supposed to "know how things work around here." And at some point you realize: the agent is smart, but it's guessing. It doesn't actually know that your orders table joins to customers on customer_id. It doesn't know your finance team excludes late refunds from quarterly revenue. It doesn't know the on-call runbook says to check a specific dashboard before paging anyone.

Nobody told it. And there was never really a good way to tell it — not in a format any tool could read, not in a way that survives being handed off between different AI systems, not in a way that lets you tell a fresh guess apart from a fact someone actually verified.

That's the gap Google Cloud built the Open Knowledge Format (OKF) to close. And the thing that makes it interesting isn't that it's clever — it's that it's almost aggressively simple. Let's walk through what it actually is.

The one-sentence version

OKF is a way to organize your organization's knowledge — schemas, definitions, playbooks, metrics, anything — as a folder of plain markdown files with a small metadata header on each one, structured just enough that any AI agent, from any vendor, can read it without needing special software.

That's really it. No database. No new file extension. No SDK to install. If you can open a text file, you already know how to read OKF.

Why does this even need to exist?

Here's the thing people miss: an AI model's training doesn't include your private, ever-changing reality. A model can be extraordinarily capable and still have zero idea what your company's revenue definition is, because that definition was never public, changes over time, and might have been decided in a meeting six weeks ago.

And this problem is getting worse, not better, as AI gets more advanced — because increasingly, it's not just humans writing this documentation anymore. Agents are writing it, updating it, and reading each other's notes. Google Cloud's own framing of this is worth sitting with: every time a team builds a new AI agent, they end up solving the exact same problem from scratch — how do we hand this thing the context it needs? — usually in some bespoke, one-off way that doesn't work anywhere else.

OKF's whole pitch is: stop reinventing this. Agree on one boring, simple format, and let every tool — yours, a vendor's, a partner company's — read the same thing.

So what does it actually look like?

Picture a folder. Inside it, files like this:

company-knowledge/
  index.md
  payments/
    orders.md
    refunds.md
  authorization/
    oauth-flow.md
    api-keys.md

Every one of those .md files is called a concept — a single, self-contained piece of knowledge. It could describe a database table, an API endpoint, a business metric, a step-by-step playbook — anything. And every concept file has exactly two parts.

Part one is a small metadata block at the very top, written in a format called YAML, sandwiched between two lines of three dashes:

---
type: BigQuery Table
title: Customer Orders
description: One row per completed order.
tags: [sales, orders]
---

This is called frontmatter, and it's the part a machine reads to quickly figure out what a file is, without having to read the whole thing. Think of it like the label on a filing cabinet drawer versus the actual folder of documents inside it.

Part two is everything below that — just ordinary markdown. Headings, paragraphs, tables, code blocks, whatever you'd normally write:

# Schema

| Column | Type | Description |
|---|---|---|
| order_id | STRING | Unique order ID |
| customer_id | STRING | Links to the customer |

That's a complete, valid OKF file. Genuinely nothing fancier than that is required.

Why YAML, and why frontmatter?

It's worth pausing on this choice, because it's not arbitrary.

The idea of splitting a file into "structured metadata up top, free content below" isn't new — it's the same pattern used by tools like Jekyll and Hugo for years to power blogs and websites. OKF borrows it because it already works: machines can quickly scan just the metadata to decide "is this relevant?" without parsing the whole document, while humans get to read the actual content as normal, readable prose.

YAML specifically was chosen because, compared to something like JSON, it's dramatically easier for a person to read and hand-write. There are no curly braces to balance, no mandatory quotation marks around every word, and — importantly — you're allowed to write comments in it. For a format meant to be edited by real people (and now, agents) on a regular basis, that readability matters more than raw technical elegance.

The only rule that actually matters

Here's something that surprises people: almost nothing about OKF is mandatory. You don't need a description. You don't need tags. You don't even need much of a body. The only thing every concept file must have is one field in its frontmatter:

type: Playbook

That's the floor. Everything else — descriptions, tags, trust signals, cross-links — is optional, layered on top when you need it. This isn't laziness; it's a design philosophy. The people behind OKF explicitly did not want to force everyone into a rigid, fixed taxonomy of "here are the only kinds of knowledge you're allowed to represent." A type can be anything descriptive — Metric, API Endpoint, Playbook, whatever fits your world — and any tool reading it is expected to gracefully handle types it's never seen before, rather than rejecting the file.

That permissiveness runs all the way through the format. Broken links between files? Tolerated — it might just mean something hasn't been written yet. Unknown extra fields someone added? Tolerated — a reader is required to preserve them, not throw them away. A file with barely any metadata at all? Still perfectly valid. OKF would rather be usable with a document that's 20% filled out than demand perfection and get nothing.

What OKF deliberately doesn't do

It's just as useful to know what this format refuses to be:

• It's not a database. It doesn't store or serve anything — it's just files.
• It's not a search engine. It doesn't rank or retrieve results for you.
• It's not a runtime. There's nothing to install or run to "use" OKF.
• It's not a fixed taxonomy. It won't tell you what kinds of knowledge you're allowed to have.

One of the cleanest lines from the people building it captures this well: what was missing wasn't another service — it was a format. Everything else, you already have.

Where this is headed

If a folder of markdown files with a metadata header sounds almost too simple to be the whole story — you're right, and that's on purpose for this post. What we've covered here is the shape of the thing: bundles, concepts, frontmatter, and the "be lenient about everything" philosophy that runs through it.

But there's a much more interesting layer sitting on top of this simple shell — one that deals with a much harder question: once agents start writing this knowledge themselves, and not just reading it, how do you know when to trust what they wrote? That's where things get genuinely clever, and it's exactly what we'll dig into in Part 2.

Next in this series: Why can't the AI just already know this stuff? A look at why training data and fine-tuning both fall short — and why structured, external context turns out to be the only thing that actually works.