collection: open knowledge format · box 01 of 01

Google's OKF Needs One Field. Version 0.2 Locks the SQL.

Most explainers still describe v0.1. We fed the reference attester five fake receipts.

Google's Open Knowledge Format asks exactly one thing of a document: a type field. Everything else is optional, and a consumer is told never to reject a file for missing it.

Six weeks after launch, version 0.2 added a rule the format had never needed. Inside a new concept type called Attested Computation, the agent may fill in the parameters but must not write or edit the query. The spec's own before-and-after example explains why: in v0.1 the SQL sat in prose that an agent can read, ignore, or rewrite.

Below: what OKF is, what v0.2 changed, what happened when we fed Google's reference checker five fake receipts, and five claims in circulation that the files do not support.

OKF is a file format for what your company knows. Think of it as a git repo where every table schema, metric definition and runbook gets its own markdown file. Google's Data Cloud team (Sam McVeety and Amir Hormati) published it as an open, Apache 2.0 spec that formalizes Andrej Karpathy's LLM Wiki pattern: instead of re-retrieving raw documents on every query, an agent maintains a curated wiki it reads and updates.

A bundle is a directory. Each markdown file is one concept, and the file path minus .md is its ID. A YAML frontmatter block holds the few fields worth querying. Ordinary markdown links between files turn the folder into a graph an agent can walk.

fig. 1 · adapted from the example in Google's launch post. title, description, resource and tags are recommended, not required.

Why a format and not another service: Google's post lists where this knowledge lives today (metadata catalogs with their own APIs, wikis and shared drives, docstrings and notebook cells, the heads of a few senior engineers). Every agent builder rebuilds the same context-assembly layer. The post also names the family OKF comes from: Obsidian vaults wired to coding agents and the AGENTS.md / CLAUDE.md convention files, each useful and each bespoke.

One framing that holds up, from an explainer by Suganthan: a sitemap lists your URLs, llms.txt points at the pages that matter, and an OKF bundle hands over the content itself.

The launch post said the full v0.1 spec fits on a single page. We diffed the two versions: v0.1 is 15,046 bytes, v0.2 is 37,748. Almost all of the growth answers one sentence in the new motivation section: a corpus is increasingly written and maintained by agents, so a reader needs to know where each fact came from and whether anyone checked it.

fig. 2 · field names from SPEC.md §5 and §13. v0.2 consumers may still read a legacy timestamp or # Citations list.

Two small design choices show who the spec expects to be editing these files. Actors follow one naming rule: reference_agent/gemini-2.5-pro for agents, human:ahormati for people, process:finance-nightly for jobs. And claims cite sources through footnotes keyed by a stable ID rather than a list position, because agents rewrite these documents constantly and a shuffled list would silently misattribute every citation.

The spec then derives three trust tiers from the verified field. Neither tiers nor source credibility are stored as scores: the spec calls a score subjective and quick to go stale, and stores the facts a reader can compute one from.

fig. 3 · tiers from SPEC.md §5.3, which calls them advisory signals, not access control. sample counts: our parse of all 53 concept files in the four sample bundles, Sept 17.

That last column deserves a closer look. Three of Google's four sample bundles were built by the reference agent from public BigQuery datasets (GA4 e-commerce, Stack Overflow, Bitcoin). Together they hold 44 concepts. All 44 carry sources, which is good. None carries a verified entry, so every one sits in the lowest tier.

The eight human-reviewed concepts all live in the fourth bundle, Acme Retail, a fictional company built to demonstrate the v0.2 fields. That is not a flaw in the spec, which says unverified files stay fully consumable. It does mean the demo that shows real data and the demo that shows trust are two different bundles, and your own agent-built corpus will look like the first kind until someone signs off.

An Attested Computation is a concept that carries a sanctioned way to compute a number, plus a way to prove the number came from it. The analogy is a pharmacy: the agent can pick the dose from a printed range, but it cannot rewrite the prescription.

The frontmatter declares a runtime (bigquery, dbt, python), typed parameters, an executor that runs the query and returns a receipt, and an attester: deterministic code, no LLM, that inspects the receipt and returns a verdict. The spec separates this from the verified field. Verified means a person or process confirmed the definition still matches policy. Attestation means this particular run produced this particular value the approved way, and it is never stored in the bundle.

fig. 4 · the consumer flow in SPEC.md §10.5, which the spec marks as informative, not normative.

Google's Acme Retail bundle ships a working attester for BigQuery. It normalizes whitespace, comments and keyword casing, then checks two things: the SQL in the receipt matches the sanctioned query, and the number about to be shown matches the first cell of the receipt's result. We called it against the bundle's revenue computation with five receipts. The dollar figures below are values we made up for the test.

fig. 5 · revenue-ytd.md takes one parameter, year. verdicts are the function's own ok field.

The two misses are documented in plain words. The file's docstring says bind values are compared as names and their values are not inspected, because the executor is trusted to bind. It also never makes a network call, so it cannot re-read a BigQuery job; it checks whatever receipt it is handed. The spec describes a stronger check (re-read the result by job ID rather than trust the agent's text) and openly defers the receipt format, the attester interface and sandboxing to a later version.

The practical catch sits in the executor. Google's sample executor is a markdown skill, and the spec says a runner can be an agent or deterministic code. If an agent follows that skill, the same agent assembles the receipt the attester trusts. The check still stops the two failures the v0.1 layout invited, a rewritten query and an improvised number. It does not yet prove the query ran, or that it answered the question the user asked.

fig. 6 · a format that adds stale_after has its own freshness problem in the docs around it.

The same connector doc keeps limits worth reading before you push anything: no entry-level access control (anyone with a basic viewer role on the project can bulk-export the entry group), scale untested beyond the 14-file demo, and deletes in git leave entries behind in the catalog.

Google gets real credit here. v0.2 followed its own versioning rule: two breaking changes, each named, each with a fallback so a v0.1 bundle still reads. The spec lists what it deferred instead of implying it shipped. The attester's docstring states its own blind spot in plain words. And the whole thing stays a folder of markdown: any editor, any git host, no SDK.

The open question is adoption on the consuming side. OKF records trust with care, then tells every reader it must not reject a file for lacking it. Whether that metadata changes anything depends entirely on consumers choosing to gate on it.

OKF v0.1 standardized where agent knowledge lives. v0.2 admits that agents can write that knowledge faster than anyone can check it, and moves the checking into fields a machine can read. The format is ready for a consumer that refuses to show an unattested number; the reference tooling is not there yet.