Open Knowledge Format (OKF): A Technical Leader's Adoption Guide

#ai #architecture #opensource #leadership

Short version: Google Cloud published the Open Knowledge Format (OKF) on June 12, 2026. It is a directory of markdown files with YAML frontmatter that any AI agent can read without an SDK, an account, or an integration. If your teams are shipping agents against internal data, OKF is a cheap way to stop each team rebuilding the same context layer.

What is the Open Knowledge Format?

OKF is an open specification for representing the metadata, context, and curated knowledge that AI systems need, published as version 0.1 by the Google Cloud Data Cloud team (Google Cloud blog). A bundle is a directory of markdown files. Each file is one concept: a table, a metric, an API, a runbook. The file path is the concept's identity, so tables/orders.md has the concept ID tables/orders (OKF v0.1 spec).

That is the whole idea. No runtime, no registry, no required tooling. Google calls v0.1 a starting point rather than a finished standard, and ships it under Apache 2.0.

Hold onto one boundary: OKF is a format, not a platform and not a search signal. It is loaded by your agents, not crawled from a public URL.

What problem does it actually solve?

The context an agent needs is mostly internal. What a metric means in your business, which table joins to which, why an API was deprecated last quarter. Google's framing is that these facts sit in metadata catalogs with their own APIs, in wikis and shared drives, in code comments, and in the heads of a few senior engineers.

So every new agent assembles the same answer from incompatible surfaces, and every catalog vendor models the same objects again. That shows up on your budget as duplicated integration work, not as a missing product. It is why the answer here is a format instead of another service.

OKF or your existing data catalog?

This is not a replacement decision. The spec lists prescribing storage, serving, or query infrastructure as an explicit non-goal, and it does not subsume domain schemas such as Avro, Protobuf, or OpenAPI. It references them instead.

Rule of thumb: if the question is where knowledge is governed, that stays a catalog decision. If the question is how knowledge travels to an agent that your catalog vendor did not build, that is OKF.

How does OKF actually work?

Frontmatter carries the few fields you want to query or filter on. The body carries what humans and models actually read.

---
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, revenue]
timestamp: 2026-05-28T14:30:00Z
---

# Schema

| Column        | Type    | Description                              |
|---------------|---------|------------------------------------------|
| `order_id`    | STRING  | Globally unique order identifier.        |
| `customer_id` | STRING  | FK to [customers](/tables/customers.md). |

Exactly one field is required: type. Everything else, including title, description, resource, tags, and timestamp, is recommended but optional. Concepts link to each other with ordinary markdown links, which makes the directory a graph rather than a tree. Two filenames are reserved: index.md for progressive disclosure and log.md for change history.

Conformance is three rules. Every non-reserved .md file has a parseable frontmatter block, every block has a non-empty type, and any index.md or log.md follows its defined structure. Consumers are told not to reject a bundle over unknown types, unknown extra keys, or broken links.

How do you roll it out?

Start where your agents are already wrong. Metric definitions and join paths are the usual first win, and they are small enough to finish.

Google shipped a reference enrichment agent that walks a BigQuery dataset, writes one concept document per table and view, then runs a second pass that crawls documentation URLs you seed it with and adds citations and join paths. It also shipped a self-contained HTML visualizer and three browsable sample bundles. Treat all of it as a proof of concept, because nothing in the format requires a particular agent framework or model.

The step that matters organizationally is the third one. Put the bundle in git, give each directory a named owner, and review changes through pull requests. Knowledge curation becomes a normal engineering activity with diffs, blame, and an approver, which is the governance mechanism most wikis never had.

Three things to know before you start

Links are untyped. A link asserts that a relationship exists, but the kind of relationship is carried by the surrounding prose, not by the link. If you need depends_on versus supersedes, you will add your own frontmatter keys. The spec permits that and tells consumers to preserve keys they do not recognize.
A writable bundle is an attack surface. If an agent enriches concepts from crawled pages or ticket text, untrusted content lands in a file that other agents read as authority. That is indirect prompt injection, the top entry in OWASP's LLM risk list. Keep agent writes behind human review and scope what the enrichment pass may fetch. Google's reference agent enforces a hard page cap and a same-host filter for exactly this reason.
Adoption is the open question, not the format. The value of any exchange format is how many parties speak it, and at launch the reference producer and consumer were both Google's. Minor versions are promised to be backward compatible, major versions may break. Your downside is bounded: if OKF stalls, you are left with well organized, version-controlled documentation.

FAQ

Does OKF improve SEO or AI search visibility?
No. It is an internal bundle your own agents load, not a public file published at a well-known URL. Schema.org markup is still what makes your web pages legible to search engines.

Does OKF replace MCP or RAG?
No. MCP is how an agent reaches tools and live systems. OKF is the durable context it reads before acting, and an MCP server can serve a bundle as a resource.

What is the license?
Apache 2.0, in the GoogleCloudPlatform/knowledge-catalog repository. Google also updated Knowledge Catalog, formerly Dataplex, to ingest OKF and serve it to agents.

What does adopting it cost?
No license and no SDK. The real cost is curation time, plus answering who owns and approves each concept document.

Is v0.1 safe to build on?
It is a draft. Bundles may declare okf_version: "0.1" in the root index.md frontmatter, and consumers that do not understand a declared version are told to attempt best-effort consumption rather than refuse the bundle.