The Format That Makes “Context Owner” Mean Something

Is Google's OKF (Open Knowledge Format) the answer?

Every few weeks, I would paste the same block of text into a chat window. Here is our API structure. Here is how our error codes are organized. Here is what “integration” means in this context. The model helps, the session ends, and it forgets everything.

A memory leak is not a workflow.

Google Cloud released the Open Knowledge Format (OKF) in June 2026 to fix exactly this. It is an open, vendor-neutral specification for storing organizational knowledge so AI agents can read, write, and share it without custom integrations. I have been building and testing a bundle. Here is what I found, how it compares to the structured authoring tools we already use, and where the gaps still are.

What OKF actually is

OKF is a directory of Markdown files with YAML frontmatter. That’s it — that’s the whole format. Each .md file represents a single concept — an API endpoint, a runbook, a database schema, a business metric. The YAML header requires only one field: type. Files link to each other using standard Markdown links, which builds a knowledge graph rather than a flat folder of text.

There is no central registry, no proprietary database, and no SDK. If you can read a text file, you can read OKF.

Here is what a YAML frontmatter block looks like in practice:

---
type: API Reference 
title: Create Mapping Collection 
description: POST endpoint for creating a new mapping collection — groups field-level mappings between two connected systems.
resource: https://api.example.com/v1/mappings 
tags: [api, mappings, integrations]
timestamp: 2026-06-15T00:00:00Z 
---

That description field is doing real work. I will come back to it.

The DITA comparison

If you’ve been in technical writing long enough, you know DITA, the Darwin Information Typing Architecture. DITA is XML-based, with strict content models, specialized topic types (concept, task, reference), and build pipelines that fail if a link is broken. DITA was designed to publish content for humans: PDFs, help systems, and multi-channel output from a single source. For regulated industries with complex publishing requirements, it is a good choice.

OKF is not competing with DITA for that job.

DITA’s consumer is a human browsing a help center. OKF’s consumer is an AI agent reading your organizational context before it writes code, answers a support ticket, or generates documentation. The strictness that makes DITA reliable — break a link, break the build — is a liability when your “reader” needs to tolerate incomplete information.

OKF’s spec states explicitly that consumers must tolerate broken links. A file that does not exist yet means that knowledge has not been written. That is an honest reflection of how organizations actually work, not a design flaw.

The other difference worth noting: DITA typically requires a specialized authoring environment — a Component Content Management System, XML editors, and schema validation. OKF runs in VS Code, Obsidian, or any text editor. It lives in a Git repo alongside the code. A data engineer can update a YAML block without routing through a CCMS or asking a writer to be a gatekeeper.

Building a bundle

I started with twelve sample files: API references, runbooks, a schema description, and a few concept files explaining domain terminology. The YAML frontmatter for each took about ten minutes to write carefully. The Markdown bodies were largely things I had already documented elsewhere — the work was in structuring the metadata and writing the description field.

Here is where writers have an advantage that most developers will miss.

Per the spec, type is the primary routing field — agents use it for filtering, categorizing, and presentation. description has a narrower defined role: a single sentence summarizing the concept, used by index generators and search snippets.

In practice, from my own testing, agents use the full frontmatter block to assess relevance — not just type. That makes description the field that carries the most semantic weight, because type alone is a category label, while the description is your one sentence of actual context. A vague description, and the agent may not connect a user’s question to the right file. A description loaded with internal jargon, and the agent cannot match it to how someone actually asks. That is the same problem writers solve when writing metadata, navigation labels, and search keywords, by the way.

A few conventions I settled on quickly:

• Write description as a precise single sentence: what the concept covers, in plain terms, that an agent can match against a user’s question. The spec defines it as one sentence; treat the constraint as a discipline to follow, and learn to work with it.

• Use a controlled type taxonomy. The spec requires only that the field exist, but if every writer on a team invents their own type names, the agent’s ability to filter collapses. Pick a vocabulary and document it somewhere accessible and available to everyone in your organization.

• Include resource URIs. Tying abstract knowledge to a specific endpoint or repository URL means an agent can do something with the information rather than just read it.

• Add an ISO 8601 timestamp and treat outdated files as a first-class maintenance problem.

The decoy test

To verify how your specific agent handles an OKF bundle — whether it filters by frontmatter or reads every file regardless — I ran a simple test. The idea came from a conversation with Gemini while researching this piece; I adapted it and ran it against my own bundle.

Build a directory with three files that have valid OKF frontmatter and short Markdown bodies. Add a fourth file as the decoy. Put the answer to your test question in the body, but give the frontmatter an irrelevant description. I used “Get more dog food from Pet Food Warehouse.”

Point your agent at the directory and ask the test question without using keywords that match the decoy’s frontmatter.

If the agent returns an answer, then it reads the decoy body despite the irrelevant frontmatter, and it is not filtering by metadata. If it says it cannot find the answer, the frontmatter is doing the filtering work. The OKF spec does not define how consumers must traverse a bundle; agent behavior here is implementation-dependent. The test tells you how your agent actually behaves, which matters more than the theoretical model.

My bundle passed. The decoy stayed unread. Worth running against whatever agent you plan to use before you commit to the architecture.

There are automated test suites you can use, such as the OKF Conformance Validator. There are others available as well. Search and find one you like.

What I am still working out

OKF is v0.1. The spec is intentionally minimal, which means conventions are still forming. A few things I do not have solved:

Type taxonomy: The controlled vocabulary problem is real. The spec defines nothing beyond requiring the field. Where the vocabulary lives — in the bundle itself, in a separate schema file, in a team style guide — is an open question. I have been keeping mine in a _meta directory at the root of the bundle. That is a workaround, not a standard.

Freshness enforcement: The timestamp field is there, but there is no enforcement. I have been adding explicit instructions to agent prompts to warn me when files are more than 90 days old. That works for now.

Scale: My test bundle is twelve files. I have not stress-tested 200 or 2000 files, where frontmatter descriptions need to distinguish between legitimately similar documents. My intuition is that the description discipline problem gets harder before it gets easier.

Bidirectional authoring: Google shipped a reference enrichment agent alongside OKF that walks a BigQuery dataset and drafts concept documents automatically. I have not tested that path yet. The appeal is obvious — seed the bundle from existing structured data, then have a writer curate the prose. Whether the generated frontmatter is good enough out of the box, or whether it needs significant human revision, I do not know yet.

The larger point

Technical writers have been making an argument for years: we are not just word processors. We understand context, govern terminology, and define what knowledge means inside an organization. It is a good argument. It has also been largely rhetorical — something you say in a job interview, not something you can point to in a file.

OKF makes the argument structural.

When you write a frontmatter description, you are deciding what the agent finds — and what it misses. A language model can generate plausible descriptions. It cannot tell you which ones are correct for this organization, this API, this definition of “integration” that means something specific here and something different in the next product line. That gap is the work.

The docs-as-code movement gave writers version control, plain text, and a seat at the engineering table. OKF is the same tools applied to a different output: instead of a website, you are building the context that your AI tools do not have by default. The file format changed. The skill set did not.

Someone in your organization is going to write those description fields. The question is whether it will be someone who knows the difference between what a document says and what it means.