What is OKF (Open Knowledge Format)? Structure, implementation and what it means for GEO

OKF (Open Knowledge Format) is an open format that represents knowledge as a directory of Markdown files with YAML frontmatter 1 . Google Cloud announced version 0.1 on 12 June 2026; the current version is 0.2, published in its own GitHub repository under the Apache 2.0 license 3 2 . Each file is a "concept", and its only required field is type 1 . OKF is not a ranking factor. But a site that already produces Markdown versions of its pages can publish a typed knowledge bundle that AI agents can read and navigate, at very little cost. This guide explains the format from its primary sources and uses roicool.com's own OKF output as the example.

What is OKF?

OKF is a vendor-neutral knowledge format written by Google Cloud's Data Cloud team. The announcement describes it as "an open specification that formalizes the LLM-wiki pattern into a portable, interoperable format" 3 . In the spec's own words the format is "intentionally minimal": a directory of Markdown files with YAML frontmatter, with no schema registry, no central authority and no required tooling 1 .

The format rests on three ideas 1 :

• Bundle: a self-contained, hierarchical collection of knowledge documents; the unit of distribution.
• Concept: a single unit of knowledge in a bundle, as one Markdown document. It can describe a table, an API, a metric or a business process.
• Concept ID: the file's path within the bundle, without the .md suffix.

Alongside the spec, the repository holds a reference agent that produces OKF bundles from BigQuery datasets, a visualizer that renders a bundle as an interactive graph, and sample bundles for GA4, Stack Overflow, Bitcoin and Acme Retail. The README calls the agent a "proof of concept"; the format itself is the contribution 2 .

Why was OKF created?

The problem OKF addresses is not web search but internal context. According to Google's announcement, most of the knowledge AI agents need is internal: the schema of a table, what a metric means in your company, the runbook for an incident. That knowledge is scattered across metadata catalogs, wikis, code comments and the heads of a few senior engineers 3 .

The starting point is Andrej Karpathy's "LLM Wiki" note. Karpathy describes a setup in which a language model reads sources and writes and maintains a persistent wiki of interlinked Markdown files itself 5 . Google's observation: the pattern keeps reappearing in Obsidian vaults, AGENTS.md-style files and "metadata as code" repositories, but every instance is bespoke. There is no agreed answer to which fields are required or what filenames mean 3 . OKF tries to be that answer.

Version 0.2 goes a step further. Knowledge is now often written and maintained by agents, and the reader has five questions: what is this based on, how much can I trust it, is it still true, is it the current version, was this number produced the way it should have been 1 ? The new fields in 0.2 make those questions answerable from the frontmatter.

Why does OKF matter for GEO and AI visibility?

The honest answer: there is no direct visibility gain today, but there is groundwork value. We draw that from three facts.

1. OKF wasn't written as a web standard. The spec explicitly lists prescribing storage, serving or query infrastructure as a non-goal 1 . It defines no HTTP path and no discovery file, and it doesn't mention llms.txt or schema.org. Its sample bundles are datasets, not websites 2 .

2. Search engines don't ask for extra files. Google says you don't need to create new machine-readable files, AI text files or markup to appear in AI Overviews and AI Mode 8 . As of October 2026, we found no documentation saying that ChatGPT, Gemini, Perplexity or Google's AI features read OKF bundles from websites.

3. Agents read Markdown, and OKF gives it structure. The llms.txt proposal notes that agents now use websites routinely and proposes serving clean Markdown versions of pages at .md URLs 6 . OKF adds three things to those Markdown versions: a type field, a graph of links between concepts, and source and freshness information 1 . Google has also updated its Knowledge Catalog to ingest OKF 3 , so a real consumer of the format exists, though for now in the enterprise data world.

So this is how we position OKF: a few hours of extra work for a site that already produces Markdown versions, and groundwork for the agent era. It shouldn't take priority for visibility. Page content, schema.org markup, crawler access and third-party sources come first; they are listed in our GEO checklist. A Turkish article on OKF from an SEO angle also stresses that OKF complements schema markup rather than replacing it 14 , and we agree.

The structure of an OKF bundle

An OKF bundle is a directory tree of Markdown files. The structure is independent of the domain; the producer organizes concepts however it likes 1 .

bundle/
  index.md          # optional: directory listing
  log.md            # optional: update history
  concept.md        # a concept at the root
  subfolder/
    index.md
    concept.md

Reserved filenames. index.md (directory listing) and log.md (update history) are reserved at every level of the hierarchy and can't be used for concepts 1 . A bundle can be distributed as a git repository (recommended), a tarball or zip archive, or a subdirectory of a larger repository 1 .

Concept files. Each concept is a UTF-8 Markdown file in two parts: a YAML frontmatter block between --- lines and a free-form Markdown body 1 . YAML has its own specification; its current revision, 1.2.2, aims to make YAML a strict superset of JSON 13 , which is why a JSON-quoted string is a valid YAML value.

The rules in the table come from section 4.1 of the spec 1 . The body has no required sections, but the headings # Schema, # Examples and # Computation have conventional meanings, and structural Markdown (headings, lists, tables, code blocks) is preferred to free prose 1 .

The new field families in 0.2. All optional; their absence carries meaning too 1 .

The actor convention. generated.by and verified[].by use one of three forms: <producer>/<version> for agents and tools, human:<id> for people and process:<id> for automated processes 1 . Trust classification keys off the human: prefix, so hand-authored or human-confirmed content must use it 1 .

Timestamps. Every timestamp in OKF is an ISO 8601 datetime with an explicit UTC offset, such as 2026-06-30T14:00:00Z 1 . A bare date (2026-06-30) names a different instant in every timezone, so it isn't valid.

index.md. It can appear in any folder and lets an agent see what's there before opening files ("progressive disclosure"). The body is a set of * [Title](relative-url) - short description lines under headings. An index.md carries no frontmatter, with one exception: the root index.md may declare the version the bundle targets with okf_version 1 .

Links. Concepts link to each other with standard Markdown links. A path relative to the bundle root (/tables/customers.md) is the recommended form; relative paths work too. A link whose target doesn't exist isn't malformed; it may point at knowledge not written yet 1 .

A real example: roicool.com's OKF output

Every page on roicool.com has a Markdown twin: a file at the page's URL plus .md. The OKF bundle is built from those twins and published under /okf/. The bundle's root index is /okf/index.md and the English index is /okf/en/index.md. The two blocks below are the output of the generator in the site's codebase (lib/markdown in the Next.js app), with long lists shortened. The site's primary language is Turkish, so the root is Turkish.

The root index, /okf/index.md:

---
okf_version: "0.2"
---

# Roicool

> Roicool, dinamik ve hedef odaklı markalar için dijitalde sürdürülebilir büyüme sağlar.

# Sayfalar

* [Ana sayfa](home.md)

# Bölümler

* [Hizmetler](hizmetler/index.md)

# Diller

* [English](en/index.md)

A concept, /okf/hizmetler/geo-ajansi.md (shortened):

---
type: "Service"
title: "GEO Ajansı"
description: "Roicool, markaların ChatGPT, Gemini, Perplexity ve Google AI Overviews cevaplarında kaynak gösterilmesini ve önerilmesini sağlayan bir GEO (Generative Engine Optimization) ajansıdır."
url: "https://www.roicool.com/hizmetler/geo-ajansi"
lang: "tr"
dateModified: "2026-10-16"
resource: "https://www.roicool.com/hizmetler/geo-ajansi"
alternates:
  en: "https://www.roicool.com/en/services/geo-agency.md"
generated: { by: "process:roicool-cms", at: "2026-10-16T09:30:00.000Z" }
related:
  - { title: "AI görünürlük analizi", resource: "https://www.roicool.com/hizmetler/ai-gorunurluk-analizi.md" }
  - { title: "GEO uyumlu içerik", resource: "https://www.roicool.com/hizmetler/geo-uyumlu-icerik.md" }
---

# GEO Ajansı Roicool: Yapay Zekâ Cevaplarında Önerilen Marka Olun

Roicool, markaların ChatGPT, Gemini, Perplexity ve Google AI Overviews cevaplarında kaynak gösterilmesini ve önerilmesini sağlayan bir GEO (Generative Engine Optimization) ajansıdır.

## Hizmetler
…

Where each rule of the spec is met in this example:

Blog posts carry one more field: sources. The post's numbered sources list is written into the frontmatter as - { id: "1", resource: "…", title: "…" } entries, so the " 1 ." marker in the text and id: "1" point at the same source 1 .

How to implement OKF, step by step

For a website, the shortest path is not to write OKF as separate content but to generate it from what you have. This is the order we followed.

1. Set the scope. Only published, indexable pages go into the bundle. Drafts, noindex pages, pages with sample data and internal notes stay out. The sitemap is the most practical source.
2. Produce a clean Markdown version of every page. No menu, footer or cookie banner; heading, definition, sections, tables and FAQ. The llms.txt proposal's .md suffix rule is a good URL scheme for these versions 6 .
3. Write a type vocabulary. Map CMS collections to types: service, industry, case study, blog post, glossary term. Types are free text, but each type should have exactly one spelling across the site 1 .
4. Fill in the frontmatter. type on the first line, then title, description and resource. The page's canonical URL is a good resource 1 .
5. Add provenance and freshness. Use generated: { by, at } for who produced the file and the content's last meaningful change, and sources for what sourced content rests on. If you don't record verification dates, don't write verified 1 .
6. Set up the bundle paths. Publish the bundle under its own root (such as /okf/), and rename any page that would be called index.md. The reserved-name rule applies in every folder 1 .
7. Generate an index.md for every folder. * [Title](relative-url) - description lines under headings, with the description taken from the concept's description 1 .
8. Declare the version in the root index. okf_version: "0.2" at the top of the root index.md only 1 .
9. Add discovery. The spec defines none, so use the web's own tools: a link to the bundle index from llms.txt, a <link> element in the page <head>, and an allow line in robots.txt. Version 2 of llms.txt recommends rel="alternate" type="text/markdown" for Markdown versions and rel="describedby" for llms.txt, as a <link> element or an HTTP Link: header 6 7 . The Link: header syntax is defined in RFC 8288 11 , and the text/markdown media type in RFC 7763 12 .
10. Validate, and repeat. After every content release, run a check that walks the whole bundle (next section).

OKF, llms.txt, schema.org and Markdown twins: the differences

All four get filed under "explaining your content to AI", but they work at different layers.

Schema.org and JSON-LD. Schema.org is a collaborative community activity that creates schemas for structured data on web pages and beyond; its vocabulary can be used with RDFa, Microdata and JSON-LD 10 . Google recommends JSON-LD for structured data where your setup allows it 9 . This layer stays inside the page and helps a search engine understand it. OKF doesn't replace it.

Markdown twin. The page's text version without the design. The llms.txt proposal suggests serving these at the page's URL with a .md suffix 6 . An OKF concept is a Markdown twin with frontmatter added, which is why a site with twins is the closest a site can be to OKF.

llms.txt. A Markdown file at the root that helps agents use a site, with a short introduction and links to detailed Markdown files 6 . llms.txt calls itself a proposal; its version 2 was published in August 2026 7 . OKF's root index.md does a similar job, but it repeats in every folder and there is a typed concept behind every entry.

Our recommended order: schema.org and page content first, then Markdown twins and llms.txt, and OKF last. Each layer builds on the one before.

How to validate OKF

OKF's conformance rule is short. A bundle conforms to 0.2 if 1 :

1. Every non-reserved .md file has a parseable YAML frontmatter block.
2. Every frontmatter block has a non-empty type field.
3. index.md and log.md, when present, follow the structure in sections 8 and 9.

Consumers have to be lenient: a bundle can't be rejected for missing optional fields, unknown type values, unknown keys, broken links or missing index.md files 1 . That leniency gives the producer no margin for error; mistakes just stay silent. So we also check the following:

We run these checks with a small Python script that starts at /okf/index.md and follows every link. Any YAML 1.2 parser is enough to parse the frontmatter 13 . To inspect a bundle visually, you can also use the reference visualizer in the OKF repository, which builds a single-file interactive graph from a local bundle folder 2 . Orphaned concepts and wrong types show up in the graph straight away.

Common mistakes

• Naming a concept index.md. The most common trap: on websites the home page's Markdown version is usually /index.md, but in OKF that name is reserved for directory listings 6 1 . We publish the home pages as home.md in the bundle.
• Putting frontmatter in subfolder index.md files. Frontmatter is allowed only in the root index.md, and only for okf_version 1 .
• Writing bare dates. stale_after: 2026-12-31 is invalid; 2026-12-31T00:00:00Z is valid 1 .
• Leaving sources in the body. In 0.2, sources replaced the v0.1 # Citations body list 1 .
• Writing verified on unverified content. The trust tier is derived from this field; without a real verification event and date, leave it out 1 .
• Spelling the same type two ways. "WebPage" and "Web Page" are two different types to a consumer. Our own audit found this on one page, and we fixed it.
• Forgetting part of the site. It is easy to take only CMS records into the bundle and miss pages generated from code. Our audit found that our free tools and brand kit were missing from the bundle, and that links to them had dropped out of the frontmatter.
• Including drafts and noindex pages. The bundle shouldn't publish anything the HTML doesn't.
• Selling OKF as a ranking trick. Google says plainly that its AI features need no extra files 8 . Be wary of any offer that sells OKF with a visibility promise.

Case study: roicool.com's OKF implementation

When we rebuilt roicool.com, we already planned a Markdown twin for every page. When OKF 0.2 came out, the decision was simple: add frontmatter and folder indexes to the twins and publish the site as a valid OKF bundle too. No separate content was written; the bundle is generated on every request from the published content in the CMS.

What we publish

Which types we use. CMS collections map to types: Home Page, Service, Sector, Case Study, Project, Blog Post, Blog Category, Person, Glossary Term, Comparison, E-book, Podcast Episode, Job Posting, Press Mention, Partnership, Legal Page, Pricing Page, Collection Page (list pages) and Tool (free tools). Each type has one spelling across the site.

How agents find the bundle. The spec defines no discovery, so we leave pointers in three places. Every page's <head> has <link rel="index" type="text/markdown" href="/okf/index.md">; index is a relation in the IANA link relations registry 15 . The optional section of llms.txt has a line pointing at the bundle index. robots.txt has an explicit allow for /okf/ and the index URL. The pages' Markdown versions are also marked with rel="alternate" type="text/markdown" 6 .

Fields we deliberately leave out. We don't write verified, because the CMS keeps no review date and the trust tier is derived from that field 1 . There's no stale_after or log.md either: since the content is generated from the published version on every request, neither adds information for now.

What the audit found (19 October 2026). We audited the bundle again against the current version of the spec. The format was conformant. We found and fixed two bugs: pages generated from code (the tools, the brand kit) were missing from the bundle and links to them were dropping out of the frontmatter, and one page spelled its type differently from the rest. We added the sources field to blog posts and put timestamp and source checks into the validation script. Next on the list are llms.txt v2's describedby recommendation 7 and an exportable archive of the bundle.

If you'd like to see where your brand stands in AI answers, our AI visibility analysis sets a baseline across four platforms. For pages written so AI can cite them, see GEO content, and for ongoing work that includes the technical layer, see our GEO agency page.