Open Knowledge Format: Google's Markdown Spec for Agents

On June 12, 2026, Google Cloud published a specification for how AI agents should read and exchange curated knowledge. You might expect a graph database, a schema registry, an SDK, and a service to run it on.

Instead, the Open Knowledge Format is this: a directory of Markdown files with YAML frontmatter.

That’s the whole format. And the restraint is the interesting part.

The Spec Is Smaller Than You Think

Most people writing about OKF have summarized the announcement. It’s worth reading the spec itself, because the surface area is startlingly small.

OKF v0.1 requires exactly one field on every concept document:

---
type: BigQuery Table
---

That’s it. type is a short string identifying what kind of concept the document describes, used for routing and filtering. Values are not centrally registered — there’s no committee approving the list of valid types. Producers pick self-explanatory descriptors and move on.

Five more fields are recommended, none required:

Field	Purpose
title	Display name. Consumers may derive it from the filename if absent.
description	One-sentence summary.
resource	A URI uniquely identifying the underlying asset.
tags	A YAML list, for cross-cutting categorization.
timestamp	ISO 8601 datetime of last modification.

Producers may add whatever custom keys they like. Consumers must preserve unknown fields rather than reject them.

A complete, conformant concept document looks like this:

---
type: BigQuery Table
title: Orders
description: One row per completed customer order.
resource: https://console.cloud.google.com/bigquery?p=acme&d=sales&t=orders
tags: [sales, orders]
timestamp: 2026-05-28T00:00:00Z
---

# Schema

| Column | Type | Description |
|--------|------|-------------|
| order_id | STRING | Unique identifier |

If you have ever written a note in Obsidian with frontmatter, you have written something very close to a valid OKF concept.

The Knowledge Graph Without a Graph Database

Here is the design decision worth stealing regardless of whether you adopt OKF.

Relationships between concepts are expressed as standard Markdown links. Not edges in a database. Not a relationships: block in the frontmatter. Just links:

Each order references a [customer](/tables/customers.md).

Bundle-relative absolute paths (starting with /) are recommended for stability; ordinary relative paths like ./other.md also work.

And then the part that makes it work: the kind of relationship is carried by the surrounding prose, not by the link. “Each order references a customer” is the edge label. There’s no ontology to maintain, no predicate vocabulary to agree on, because natural language already has one and the consumer is a language model.

A decade of knowledge-graph tooling went into formalizing relationship types so machines could interpret them. OKF’s bet is that this is no longer necessary — the machine reads English now.

Two Reserved Filenames

Only two filenames have special meaning inside a bundle:

• index.md — a directory listing that enables progressive disclosure. It carries no frontmatter. An agent reads the index first and follows only the links it needs, rather than loading every concept into context.
• log.md — a chronological update history, using ISO 8601 date headings, newest first.

Every other .md file is a concept document. A bundle ends up looking like an ordinary, browsable folder:

sales/
├── index.md
├── datasets/orders_db.md
├── tables/orders.md
└── metrics/weekly_active_users.md

index.md is the quietly important one. It’s the same instinct behind a well-written CLAUDE.md: don’t dump the library into the context window, hand the agent a table of contents and let it fetch.

What OKF Is Not

It is not RAG. RAG re-derives knowledge at query time by retrieving raw chunks and hoping the relevant ones surface. An OKF bundle stores curated, cross-linked concepts that an agent reads and updates directly. The curation happens once, deliberately, instead of being approximated on every query.

It is not AGENTS.md or CLAUDE.md. Those are instruction files — they tell an agent how to behave in a repository. OKF describes subject-matter knowledge: what this table means, how this metric is defined, why this dataset has a gap in March. Different job, complementary.

It is not MCP. MCP is a runtime protocol for connecting an agent to live systems. OKF is a file format sitting at rest on disk. You would plausibly use both: MCP to reach the warehouse, OKF to explain what’s in it.

The Conformance Rules Are Deliberately Forgiving

A bundle conforms to OKF v0.1 if every non-reserved .md file has parseable YAML frontmatter, every frontmatter block has a non-empty type, and the reserved files follow their structures when present.

More telling is what the spec forbids consumers from doing. A consumer must not reject a bundle because of missing optional fields, unknown type values, unknown keys, broken cross-links, or a missing index.md.

That’s a format designed by people who expect bundles to be half-finished, partly machine-generated, and constantly in flux — which is what real knowledge bases actually look like. Strict formats die of their own strictness. This one is built to survive contact with a messy folder.

Google shipped reference tooling alongside it: a BigQuery enrichment agent, a static HTML visualizer, and three sample bundles.

One caveat worth stating plainly: OKF is v0.1, and explicitly a draft. The spec is versioned and designed for backward-compatible growth, but field names and conventions can still move. Don’t rebuild your knowledge base around it today. Do note which way the standard is pointing.

Why This Matters Beyond Google Cloud

Strip away the BigQuery examples and OKF is a bet with a much wider blast radius: that the durable format for machine-readable knowledge is plain Markdown files in a folder you own.

Not a proprietary catalog with an API. Not embeddings in a vector store you can’t read. Not a wiki with an export button that mangles your tables. Files. On disk. Diffable, greppable, portable between vendors, readable by a human and by every model on the market.

It’s the same conclusion Claude Code, Cursor, Copilot, and Windsurf all arrived at independently when they picked Markdown as their instruction format. Google Cloud writing it down as a spec is confirmation, not invention.

Where Minibase Fits

If you keep a Minibase Vault, you already maintain something structurally close to an OKF bundle: a folder of Markdown files with frontmatter, on your own disk, read by Claude and ChatGPT.

Making it formally conformant is a small edit — add a type to your frontmatter, and let your links do the rest:

---
type: Article
title: How the Open Knowledge Format can improve data sharing
resource: https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing/
tags: [okf, agents, markdown]
timestamp: 2026-07-19T00:00:00Z
---

That’s the practical shape of this announcement. The hard part of an agent knowledge base was never the file format — it was getting good source material into it. A specification tells you how to shape the folder. It doesn’t fill it.

Minibase is the part that fills it: one click turns any webpage — documentation, a GitHub README, a spec, a thread, a research paper — into clean Markdown sitting in your folder, ready for the next agent you run.

The format is now standard. What you put in it is still your edge.

---

Minibase turns any webpage into clean Markdown your agents can read — install the extension and start building the bundle that makes your agents smarter.