--- title: "How to Adopt Google's Open Knowledge Format (OKF) in 2026" description: "A hands-on guide to adopting Google's Open Knowledge Format (OKF): what changed since launch, how to structure a bundle, the conformance rules, and how to start today with MDflow." author: "MDflow" date: 2026-07-11 reading_time: "13 min" canonical_url: https://mdflow.cz/blog/open-knowledge-format-adoption-guide md_url: https://mdflow.cz/blog/open-knowledge-format-adoption-guide.md --- # How to Adopt Google's Open Knowledge Format (OKF) in 2026 *Published July 11, 2026 · 13 min read* Google's [Open Knowledge Format (OKF)](/blog/google-open-knowledge-format-okf) landed on June 12, 2026 as a deliberately small idea: write down what your organization knows as plain Markdown files that any AI agent can read. In the weeks since, the sketch has hardened into a real specification with conformance rules — and a small ecosystem of guides and tools has started to form around it. This is the practical follow-up to our OKF explainer. Less "what is it," more "how do I actually adopt it." Below: what has firmed up since launch, a step-by-step guide to building your first conformant bundle, and how to start today without adopting any platform — including with MDflow. > **TL;DR** — An OKF bundle is a directory of Markdown files, each describing one concept, each with YAML frontmatter carrying at least a `type`. Add `index.md` files for navigation, cross-link concepts with `/`-rooted links, distribute as a git repo, and you are conformant. No SDK, no database, no Google Cloud account. If you already write Markdown, adoption is mostly organizing what you have. [MDflow](/) gives that bundle a home people and agents can both read and update. ## What is the Open Knowledge Format? The Open Knowledge Format is an **open, vendor-neutral specification for representing curated knowledge as Markdown**. A bundle is a directory of `.md` files; each file describes one *concept* — a table, a metric, a runbook, an API, a policy — using YAML frontmatter for the handful of fields that need to be machine-readable and ordinary Markdown for everything else. The whole point is portability. As the spec puts it, knowledge should be "readable by humans without tooling, parseable by agents without bespoke SDKs, diffable in version control, and portable across tools, organizations, and time." If you want the full background — why it matters, how it compares to RAG, `llms.txt`, and MCP — read the [OKF explainer](/blog/google-open-knowledge-format-okf). This post assumes you are sold on the idea and want to ship one. ## What's changed since launch OKF shipped as **v0.1** and was explicitly framed as "a starting point, not a finished standard." In the short time since, the public `SPEC.md` has clarified the vocabulary and, importantly, the **conformance rules** — the difference between a nice idea and something different producers and consumers can rely on. The pieces worth knowing before you adopt: - **A precise vocabulary.** A **Knowledge Bundle** is "the unit of distribution." A **Concept** is one Markdown document. A **Concept ID** is the file path with the `.md` suffix removed — so `tables/orders.md` has the ID `tables/orders`. That ID is what cross-links point at. - **A new reserved file: `log.md`.** Alongside `index.md` (a directory listing for progressive disclosure), the spec now reserves `log.md` for a **chronological history of changes**. Both filenames are reserved at any level and must not be used as concept documents. - **Explicit versioning.** Bundles may declare their target version with `okf_version: "0.1"` in the root `index.md` frontmatter. Versioning follows `.`: minor bumps are backward-compatible additions, major bumps may break. - **Cross-linking rules.** A link from concept A to concept B "asserts a relationship." Links may be **absolute (bundle-relative)** — starting with `/`, interpreted from the bundle root, and recommended for stability — or ordinary **relative** Markdown paths. Consumers **MUST tolerate broken links** rather than fail. - **Liberal conformance.** The bar is deliberately low so the format spreads: a bundle is conformant if every non-reserved `.md` file has parseable frontmatter with a **non-empty `type`**. Consumers **MUST NOT reject documents with unrecognized fields**, and **SHOULD treat everything else as soft guidance**. Forgiving by design. - **Distribution formats.** A bundle can ship as a **git repository** (recommended — you get history, attribution, and diffs for free), a tarball or zip archive, or a subdirectory inside a larger repo. - **An ecosystem forming.** Beyond Google's own [blog post](https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing/) and [reference repo](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf), independent explainers, annotated spec guides, and "is it worth adopting yet" deep dives have begun to appear — the earliest signal that OKF is being treated as a shared format, not just a Google artifact. None of this changes the spirit of v0.1. It just means you can now adopt against a written contract instead of a vibe. ## How to adopt OKF: a hands-on guide You do not need a tool to produce a conformant bundle — a text editor and a folder will do. Here is the whole loop. ### 1. Decide what a "concept" is for you Pick the smallest reusable unit of knowledge your agents keep needing. For a data team that is often a table, a dataset, or a metric. For a platform team it is a service, a runbook, or an architecture decision. For a product team it is a policy, a feature, or a troubleshooting guide. Each concept becomes one file. ### 2. Write a concept file Give every concept file YAML frontmatter with a required `type`, then whatever recommended fields help, then Markdown for the substance: ```yaml --- type: metric title: Weekly Active Users description: Distinct users with at least one session in the trailing 7 days. resource: https://console.cloud.google.com/bigquery?p=acme&d=analytics&t=wau tags: [growth, product] timestamp: 2026-07-10T09:00:00Z --- # Definition A user is "active" if they have one or more sessions in the trailing 7 days, measured in UTC. Deduplicated on `user_id`. # Source Computed from [events](/tables/events) joined to [users](/tables/users) on `user_id`. ``` Only `type` is required. Everything else is optional and a consumer must not choke on fields it does not recognize — so you can add your own keys freely. ### 3. Add `index.md` for progressive disclosure At each level of the hierarchy, an `index.md` describes what lives in that folder so an agent can decide whether to go deeper before it reads every file. In the root `index.md`, declare the version: ```yaml --- type: index title: Acme Analytics Knowledge okf_version: "0.1" --- # Acme analytics knowledge Curated tables, datasets, and metrics for the Acme data warehouse. - `tables/` — table-level schemas and join paths - `metrics/` — canonical metric definitions - `datasets/` — dataset-level descriptions and ownership ``` A workable layout: ```text acme-analytics/ ├── index.md ├── log.md ├── tables/ │ ├── index.md │ ├── orders.md │ └── customers.md └── metrics/ ├── index.md └── weekly_active_users.md ``` ### 4. Cross-link concepts Wire the graph together with Markdown links. Prefer **bundle-relative** links that start with `/` and point at the Concept ID (no `.md`), because they survive files moving around: ```markdown Joined with [customers](/tables/customers) on `customer_id`. ``` A link is a *relationship*, and any conformant consumer must tolerate the occasional broken one — so linking generously is safe. ### 5. Record history in `log.md` (optional but recommended) Keep a chronological `log.md` at the root (or per folder) noting what changed and when. This is exactly the bookkeeping that humans abandon and agents excel at — an agent updating a definition can append a log entry in the same pass. ### 6. Distribute it as a git repo Put the directory in git. You now have history, attribution, diffable pull requests, and CI hooks for free — and a bundle any OKF consumer can clone, index, or serve to an agent. That is the entire adoption path. **Quick conformance checklist:** every concept file has parseable frontmatter with a non-empty `type`; `index.md` and `log.md` are used only for their reserved purposes; cross-links prefer `/`-rooted Concept IDs; the root `index.md` declares `okf_version`. Meet those and you are v0.1-conformant. ## Why adopt OKF — for developers and AI agents **For developers, the win is that knowledge becomes code.** A bundle is just files, so it lives in git: versioned, reviewed in pull requests, and subject to the same CI you already run. There is no SDK to learn and no lock-in — the same bundle works whether you switch clouds, models, or agent frameworks. Producer and consumer are cleanly separated, so whoever *writes* the knowledge (a person, a pipeline, an enrichment agent) is decoupled from whoever *reads* it. **For AI agents, the win is curated context instead of guesswork.** Unlike retrieval-augmented generation, which re-derives meaning from raw chunks at query time, an OKF bundle hands an agent concepts someone already got right — with `type` and `tags` to filter on, `index.md` to navigate, and cross-links to traverse. Less hallucination, more provenance. And because agents "don't get bored" doing bookkeeping, they can keep the bundle current — the exact chore that causes humans to abandon wikis. ## Which applications benefit most 1. **Data and analytics platforms** — OKF's home turf. Table schemas, metric definitions, and "talk to your warehouse" assistants need precisely the typed, cross-linked concepts OKF encodes. 2. **Internal developer platforms** — runbooks, architecture decision records, and service catalogs that already want to be Markdown in a repo. 3. **AI coding assistants** — Cursor, Claude Code, and Codex thrive on repo-local Markdown; a conformant bundle upgrades ad-hoc notes into a navigable knowledge base. 4. **Customer-facing copilots** — product docs and policies become a governed, citable source of truth instead of a brittle pasted prompt. 5. **Second-brain and PKM tools** — the ones that are *markdown-native* (not Markdown-as-export) adopt OKF with the least friction. ## How MDflow fits We did not build [MDflow](/) to implement OKF — the spec did not exist when we started. But because we made the same core bet (**knowledge should be portable Markdown that people and agents can both read**), an MDflow workspace already lines up with most of a bundle. If you would rather adopt OKF in a hosted editor than hand-manage a git repo, here is what maps today. ### What already lines up - **Markdown-native storage.** Every MDflow document is plain-text Markdown — what you write is what an agent reads. That is OKF's "just Markdown, just files" principle in production. - **Folder descriptions ≈ `index.md`.** Every MDflow folder carries a **description** that defines the intended context for what's inside, and folders **nest to any depth**. Those descriptions **cascade**: open any document and MDflow returns the compounded chain of context from the top of your workspace down to where you are. That is OKF's nested-folders-with-`index.md` progressive disclosure, already live. - **Version history ≈ `log.md`.** MDflow captures automatic version history on every write path — editor, API, and agent — with line diffs and one-click restore. That is the chronological change record OKF reserves `log.md` for. - **Raw `.md` with YAML frontmatter, over open CORS.** Append `.md` to any shared MDflow link to get the document as plain Markdown with frontmatter and `Access-Control-Allow-Origin: *` — the same frontmatter-on-Markdown shape OKF formalizes. (This post has a raw `.md` twin; see the link near the top.) - **Producers *and* consumers.** OKF assumes agents both read and update knowledge. MDflow's [HTTP API](/docs/api) and [MCP server](/docs/mcp), authenticated with a Personal Access Token, let Claude, ChatGPT, Cursor, and Codex create, update, move, and organize documents — and [`mdflow_get_context`](/docs/mcp) is the consumer side, ranking folder descriptions first and returning the most relevant bodies. - **Discovery and governance built in.** MDflow ships an [`llms.txt`](/llms.txt) index, an agent card, and an OpenAPI spec for discovery, plus public and private sharing, [collections](/faq), anchored comments, and optional client-side encryption for governance. ### Where we are headed This is **direction, not a dated commitment**, but OKF sharpened our roadmap: - **Native `type` and `tags`.** Adopting OKF's reserved fields as first-class, editable metadata on every document. - **OKF import and export.** Round-tripping a folder or [collection](/faq) to and from a conformant bundle — a directory of `.md` files with `index.md` context and a `log.md` from version history. - **Collections as bundles.** Serving a whole collection to agents as one cross-linked bundle over HTTP, so an agent can pull a curated knowledge set at once. - **Capture-to-knowledge.** The [MDflow Web Clipper](/clipper) already turns web pages into clean Markdown; the next step is dropping clipped pages straight into a typed, agent-ready bundle. - **Agent-assisted enrichment.** Google's reference implementation auto-drafts and enriches OKF documents; the same fits MDflow — let an agent propose folder descriptions, types, and cross-links for knowledge you already have. ## The bottom line OKF is small on purpose, and adopting it is mostly organizing what you already write. Create a directory of Markdown concepts, give each a `type`, add `index.md` navigation and `/`-rooted cross-links, keep a `log.md`, and ship it as a git repo. That is a conformant bundle — no platform required. For developers, that means knowledge that lives in git and never goes stale. For AI agents, it means curated, citable context instead of guesswork. MDflow is where that knowledge can live for people and agents at the same time: write Markdown in the browser, give your folders meaning, keep automatic history, and connect your agents — all today, with a roadmap pointed straight at OKF import and export. [Start free](/login) · [Connect an AI agent](/docs/mcp) · [Read the API docs](/docs/api) ## Frequently asked questions ### How do I start using Google's Open Knowledge Format (OKF)? Create a directory of Markdown files where each file describes one concept, and give every file YAML frontmatter with at least a `type` field. Add an `index.md` in each folder for progressive disclosure, cross-link concepts with bundle-relative links that start with `/`, and distribute the whole directory as a git repository. That directory is a conformant OKF bundle — no SDK, database, or Google Cloud account required. ### What is the minimum a file needs to be OKF-conformant? Every non-reserved `.md` file must contain parseable YAML frontmatter with a single required field: a non-empty `type`. Recommended fields (`title`, `description`, `resource`, `tags`, `timestamp`) are optional, and consumers must not reject a document for using extra or unknown fields. The reserved filenames `index.md` and `log.md` have defined meanings and must not be used as concept documents. ### What changed in OKF since it launched in June 2026? OKF launched on June 12, 2026 as v0.1. The public `SPEC.md` has since firmed up the vocabulary and conformance rules: a Knowledge Bundle is the unit of distribution, a Concept is one Markdown file, a Concept ID is the file path without the `.md` suffix, `log.md` is reserved for change history, cross-links may be absolute (bundle-relative, starting with `/`) or relative, and bundles can declare `okf_version` in the root `index.md`. A community of third-party guides and consumers has also started to appear. ### Do I need Google Cloud or an SDK to adopt OKF? No. Google describes OKF as a "format, not a platform." A bundle is just Markdown, files, and YAML frontmatter, so it works in any git repo, filesystem, or editor. Google Cloud's Knowledge Catalog can ingest bundles, but nothing about the format requires a proprietary account, database, or SDK to read or write. ### How does MDflow help me adopt OKF? MDflow already stores everything as portable Markdown, gives every folder a description that cascades into curated context (OKF's `index.md` progressive-disclosure idea), serves raw `.md` with YAML frontmatter over open CORS, keeps automatic version history (OKF's `log.md` idea), and exposes the whole workspace to agents over an MCP server and HTTP API. That means an MDflow workspace is close to an OKF bundle today, and agents can both read and maintain it. ## Further reading - Google Cloud — [How the Open Knowledge Format can improve data sharing](https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing/) - GoogleCloudPlatform — [OKF spec, reference implementations, and sample bundles on GitHub](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf) - GoogleCloudPlatform — [OKF SPEC.md (v0.1 draft)](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md) - MDflow — [Google's Open Knowledge Format (OKF), explained](/blog/google-open-knowledge-format-okf) · [Folder descriptions as agent context](/blog/folder-descriptions-agent-context) · [MCP documentation](/docs/mcp) · [API documentation](/docs/api) · [FAQ](/faq)