Most teams don’t suffer from a lack of data. They suffer from a lack of shared context. Definitions, caveats, ownership, and “how to use this safely” guidance end up scattered across wikis, tickets, dashboards, and people’s heads. Google’s Open Knowledge Format (OKF) tackles that sprawl by packaging curated context as a portable, versionable bundle of “just files” that both humans and AI agents can consume reliably (Google Cloud Blog, Jun 12 2026, OKF SPEC.md).
This article covers the problem OKF targets, what the format is (and isn’t), and the building blocks that make it work. It then explains why OKF fits developer workflows and content operations, plus adoption patterns, tradeoffs, and practical next steps.
The real problem OKF is trying to solve: “context sprawl”
OKF exists because the most important knowledge in an organization often isn’t the data itself. It’s the context around the data, and that context is scattered. Google describes this as “metadata, context, and curated knowledge” spread across too many surfaces to share or reuse cleanly (Google Cloud Blog, Jun 12 2026).
This fragmentation hurts humans. It hurts AI agents and cross-team work even more. People compensate with experience. They know which wiki is “more correct,” who to ask, and which dashboard is legacy. Agents don’t have that intuition. When context is missing or split across systems, an agent has to infer and guess. That leads to confident wrong answers and brittle automations.
It also helps to separate data from context:
- Data: table schemas, API contracts, dbt models.
- Context: metric definitions, caveats, ownership, join guidance, deprecations, and runbooks.
Without context, two teams can query the same table and still disagree on what “revenue” means.
Before OKF, a developer debugging a revenue discrepancy might find SQL in a dashboard, a definition in a wiki page, and a deprecation note buried in a ticket. Then they repeat the same archaeology next week. OKF is positioned as a portable corpus that tools (and agents) can consume, not as “another portal.”
What OKF is (and what it is not)
The simplest way to understand OKF is as a file-based packaging standard for curated knowledge. It’s small enough to live in git, structured enough to index, and neutral enough to move across tools.
OKF in one sentence: a directory of Markdown + YAML frontmatter
Per Google’s announcement and the specification, OKF is a vendor-neutral way to package curated organizational knowledge as a directory of Markdown files. Each file includes YAML frontmatter for structured metadata (Google Cloud Blog, Jun 12 2026, OKF SPEC.md). The key idea is that it’s “just files.” There’s no required SDK, runtime, schema registry, or central service.
Markdown plus YAML is a deliberate trade. Humans can review it in pull requests, and diffs stay readable. Tools can parse the frontmatter to index and retrieve concepts consistently.
---
type: metric
title: "Revenue (Net)"
description: "Net revenue excluding refunds and chargebacks."
resource: bigquery://analytics.metrics/revenue_net
tags: [finance, gaap, executive-dashboard]
timestamp: 2026-06-12T00:00:00Z
---
Metric notes, caveats, and links go here in Markdown.
What OKF is not: not a replacement for domain schemas or APIs
The spec is explicit that OKF doesn’t replace domain-specific schemas or interface definitions such as Avro, Protobuf, OpenAPI, or dbt models (OKF SPEC.md). Instead, it acts as a curation and metadata wrapper. It points at sources of truth and adds context they don’t capture well, like usage guidance and operational notes. This reduces schema duplication and helps avoid “two sources of truth.”
---
type: api-endpoint
title: POST /v1/orders
resource: https://api.example.com/openapi.yaml#/paths/~1v1~1orders/post
tags: [orders, public-api]
timestamp: 2026-06-12T00:00:00Z
---
Use `Idempotency-Key` for retries. Deprecated fields: `promoCode` (use `discounts[]`).
Common confusion: OKF vs Google Knowledge Graph / schema.org markup
OKF is for internal, file-based knowledge bundles meant to be shared and used by tools and agents. The Google Knowledge Graph Search API is different. It’s a hosted service that returns entity results as JSON-LD using schema.org types (Knowledge Graph Search API docs). A quick check helps: OKF lives in repos and filesystems. Knowledge Graph is an online entity search API.
How OKF works: the building blocks developers can reason about
Once you accept “it’s just files,” the next question is how those files become something tools can index, link, and retrieve. OKF’s answer is a small set of filesystem-friendly rules.
Knowledge Bundles, Concepts, and Concept IDs
The spec defines a filesystem-native mental model (OKF SPEC.md):
- A Knowledge Bundle is a distributable directory tree.
- Each Concept is exactly one Markdown document.
- The Concept ID is derived from the file path (minus
.md).
Path-based IDs stay stable under version control. They also make it easy for tools to reference concepts without inventing a separate identifier scheme.
knowledge-bundle/
datasets/
ga4_ecommerce.md # conceptId: datasets/ga4_ecommerce
tables/
ga4/events.md # conceptId: tables/ga4/events
metrics/
revenue_net.md # conceptId: metrics/revenue_net
runbooks/
revenue_discrepancy.md # conceptId: runbooks/revenue_discrepancy
YAML frontmatter as the “queryable surface area”
OKF keeps structure intentionally small. Google highlights a compact set of frontmatter fields, type, title, description, resource, tags, timestamp, that tools can index for filtering and routing (Google Cloud Blog, Jun 12 2026). The spec defines the normative rules (OKF SPEC.md).
This is what makes “retrieve all runbooks tagged incident-response” a metadata query instead of a full-text guessing game.
---
type: metric
title: Revenue (Net)
description: Net revenue excluding refunds and chargebacks.
resource: bigquery://analytics.metrics/revenue_net
tags: [revenue, finance]
timestamp: 2026-06-12T00:00:00Z
---
Markdown body as the “human-first, agent-usable” narrative layer
OKF uses plain Markdown for the body. That keeps content readable in GitHub or internal doc sites. It also stays easy for agents to chunk, quote, and follow links. Links express relationships beyond folders. For example, a metric can point to its source table and the runbook for incidents.
See source table: ../tables/ga4/events.md
Incident response: ../runbooks/revenue_discrepancy.md
Why OKF matters for developers: interoperability, workflows, and agent grounding
With the mechanics in place, the developer value becomes clearer. OKF is a low-friction interchange format that fits engineering workflows while making agent grounding more dependable.
Interoperability without glue code: “format, not service”
OKF matters to developers because it’s a format you can move around, not a platform you must integrate with. Bundles are “just files,” so producers and consumers only need filesystem access plus a Markdown/YAML parser (Google Cloud Blog, Jun 12 2026, OKF SPEC.md). You can keep a bundle in git, publish a pinned tarball for reproducible runs, or mount it into an environment where tools and agents can read it.
A concrete payoff is cross-stack reuse. A data platform team can publish a bundle once. Then a Python agent pipeline, a TypeScript IDE helper, and a catalog ingestion job can all consume the same directory tree.
“Knowledge as code” practices applied to context
Because OKF is diffable text, it fits normal engineering discipline. Metric definitions and runbooks can be updated via PRs, reviewed by owners, and rolled back when needed. That turns “why did this number change?” into a git blame instead of a Slack archaeology expedition. The spec’s version-control friendliness is the enabling detail (OKF SPEC.md).
In practice, teams add CI gates that keep the bundle coherent:
# Example CI gate: fail if any concept link points to a missing file
python scripts/check_links.py knowledge-bundle
Better agent grounding: fewer hallucinations, more reliable automation
Google frames OKF as a way to ground agents with the right context. That includes definitions, caveats, deprecations, and operational procedures (Google Cloud Blog, Jun 12 2026). Stable concept IDs plus queryable frontmatter let retrieval start narrow (by type and tags). Tools can then traverse links to assemble the “full story” for a task.
---
type: runbook
title: Revenue discrepancy triage
tags: [incident-response, revenue]
timestamp: 2026-06-12T00:00:00Z
---
An incident bot can pull the runbook and route to the right owner. An analytics agent can retrieve the metric concept to avoid using the wrong definition.
Why OKF matters for content creators: an “LLM-wiki” you can ship
Developers care about interoperability and workflow fit. Content creators care about portability, editorial control, and reuse across audiences and tools. OKF is designed to meet those needs without forcing a single publishing platform.
OKF as a standardized, portable “LLM-wiki” pattern
OKF turns the “LLM-wiki” idea into something teams can adopt without committing to one wiki product. Google frames the format as a way to standardize that pattern: write human-readable Markdown, add a small amount of structured metadata, and ship the result as a bundle of files (Google Cloud Blog, Jun 12 2026).
That portability is the unlock. A docs team can curate a product-concepts/ bundle for feature behavior and deprecations. A data team can curate an analytics-concepts/ bundle for metrics, tables, and runbooks. You can publish both internally, open-source a subset, or share across org boundaries.
Metadata that makes content discoverable and reusable
YAML frontmatter is what makes OKF feel less like “a folder of docs” and more like a queryable knowledge base. Tags let you slice content by audience or lifecycle (deprecated, oncall, exec). resource anchors a concept to the system of record. timestamp provides a freshness signal that search and agents can respect.
Over time, editors can standardize templates per type, so readers recognize the shape quickly.
---
type: runbook
title: Payments latency spike
description: Triage and mitigation steps for elevated p95 latency.
resource: https://monitoring.example.com/dashboards/payments
tags: [incident-response, payments, oncall]
timestamp: 2026-06-12T00:00:00Z
---
## Symptoms
## Diagnosis
## Mitigation
## Escalation
Publishing and maintenance workflows that don’t fight your tools
Because OKF uses Markdown, it renders cleanly on GitHub/GitLab. It can also sync into an internal docs portal without rewriting content. Google highlights shipping bundles as artifacts, which maps well to editorial release trains (Google Cloud Blog, Jun 12 2026). For example, you can run a monthly “data platform bundle” release with changelogs, review rotations, and a style guide.
Practical adoption patterns
OKF is simple in theory. Adoption succeeds when you use that simplicity to enforce clarity, not to create near-duplicate docs.
Pattern: concept-per-file bundles organized by domain
The spec’s “concept-per-file” rule is easiest to run when you organize by domain folders. Express relationships as links rather than mega-pages (OKF SPEC.md). A simple starting tree keeps concepts small enough to reuse.
knowledge-bundle/
metrics/revenue_net.md
tables/orders.md
policies/refunds.md
runbooks/revenue_discrepancy.md
Inside metrics/revenue_net.md, keep the YAML frontmatter queryable. Use Markdown links to connect the graph:
---
type: metric
title: Revenue (Net)
resource: bigquery://analytics.marts/revenue_net
tags: [revenue, finance]
timestamp: 2026-06-12T00:00:00Z
---
Derived from [Orders table](../tables/orders.md). Refund handling: [Refund policy](../policies/refunds.md).
Pattern: distribute OKF as an artifact (repo, release, filesystem)
Because bundles are “just files,” distribution is a packaging decision. Use a git repo for collaboration and review. Publish tarball releases for pinned, reproducible consumption. Optionally sync to a shared mount for runtime access (Google Cloud Blog, Jun 12 2026).
For agents, pin explicitly, for example: “use bundle v2026.06 for this workflow run.” That prevents retrieval from drifting mid-incident.
tar -czf knowledge-bundle.tgz knowledge-bundle/
# attach knowledge-bundle.tgz to a release like v2026.06
Pattern: pair OKF with catalog ingestion (Google Cloud Knowledge Catalog example)
Google says Google Cloud Knowledge Catalog can ingest OKF and serve it to agents (Google Cloud Blog, Jun 12 2026). This split is useful. OKF stays the interchange layer. Catalogs become optional UX and indexing layers, not the only home for context.
For more background on the product direction, see Google’s Knowledge Catalog introduction (Knowledge Catalog blog, Apr 22 2026).
Tradeoffs and pitfalls: where teams stumble and how to avoid it
OKF is intentionally minimal, which makes it portable. The work doesn’t disappear. It shifts into conventions and maintenance.
Inconsistent conventions reduce interoperability
Minimal structure is also a sharp edge. If every team invents its own type values, tag styles, and linking habits, cross-bundle queryability drops. That undermines the standardization OKF is meant to enable (OKF SPEC.md).
Treat conventions as part of the product:
- Define a shared
typetaxonomy. - Use a controlled tag vocabulary (including casing).
- Require consistent Markdown sections per
type. - Standardize link patterns (relative links, concept-per-file).
A common failure mode is tag casing drift. One team writes incident-response, another writes IncidentResponse, and filters miss half the runbooks. Fix it with templates, review checklists, and CI that rejects nonconforming metadata.
# scripts/normalize_tags.py
import sys, pathlib, re, yaml
def load_frontmatter(text: str):
m = re.match(r"^---\n(.*?)\n---\n", text, re.S)
return (yaml.safe_load(m.group(1)) or {}) if m else {}
root = pathlib.Path(sys.argv[1])
bad = []
for md in root.rglob("*.md"):
fm = load_frontmatter(md.read_text(encoding="utf-8"))
tags = fm.get("tags") or []
if any(t != t.lower() for t in tags):
bad.append(str(md))
if bad:
raise SystemExit("Non-lowercase tags in:\n" + "\n".join(bad))
Treating OKF as the system of record for schemas
OKF does not replace domain schemas like Avro, Protobuf, or OpenAPI (OKF SPEC.md). Use it to explain and operationalize them. Keep it focused on rationale, caveats, examples, deprecations, and safe usage guidance. A simple rule helps: resource must point to the canonical source-of-truth location.
---
type: api-endpoint
title: CreateOrder
resource: https://repo.example.com/apis/orders/openapi.yaml#/paths/~1v1~1orders/post
tags: [orders, public-api]
timestamp: 2026-06-12T00:00:00Z
---
Retries require `Idempotency-Key`. `promoCode` is deprecated; use `discounts[]`.
Stale knowledge and missing freshness signals
Bundles rot unless you operationalize freshness. Google calls out timestamp as part of the structured fields (Google Cloud Blog, Jun 12 2026). Use it to power staleness dashboards and enforcement, especially for runbooks.
Add ownership conventions, review SLAs, and automated reminders. For high-risk concepts, add a “Last verified” line in Markdown.
# Fail CI if any incident runbook is older than 90 days
python scripts/check_staleness.py knowledge-bundle --type runbook --tag incident-response --max-age-days 90
How to get started: next steps for developers and content teams
Treat OKF like any shared interface. Start with a small, high-value surface area. Lock down conventions early. Add enough automation to keep the bundle trustworthy.
1. Start small: pick one high-value domain and define conventions
Start where missing context repeatedly burns time. Good candidates include your top executive metrics, the most-queried tables, or on-call runbooks. Keep the first bundle small. Prove the workflow (author → review → publish → consume) before scaling.
Define conventions up front:
- A minimal
typelist you will actually use (for examplemetric,table,runbook,dataset) - A tag vocabulary with consistent casing
- One Markdown template per
type
Google points to sample bundles (GA4 e-commerce, Stack Overflow, Bitcoin) in its announcement. Keep the spec open while you implement so you follow the normative rules (Google Cloud Blog, Jun 12 2026, OKF SPEC.md).
2. Add quality gates: validation, link checks, and publishing
Because OKF requires no tooling, you can add lightweight CI checks that match your conventions. Common gates include required frontmatter fields, forbidden tags, and broken relative links. If you want stricter guarantees, add JSON Schema validation.
A simple first gate is ensuring Concept IDs (path minus .md) are unique and indexable:
# scripts/index_concepts.py
import sys, pathlib
root = pathlib.Path(sys.argv[1])
ids, dupes = set(), []
for md in root.rglob("*.md"):
cid = md.relative_to(root).with_suffix("").as_posix()
if cid in ids:
dupes.append(cid)
ids.add(cid)
if dupes:
raise SystemExit("Duplicate concept IDs:\n" + "\n".join(dupes))
print(f"Indexed {len(ids)} concepts")
Publish in two forms: rendered docs (GitHub Pages or an internal portal) and a pinned bundle artifact (release tarball) for agents.
3. Decide how agents will consume it
Plan for multiple consumption modes without changing content. Options include direct filesystem reads, an indexing pipeline for RAG, or catalog ingestion. Google notes that Knowledge Catalog can ingest OKF and serve it to agents (Google Cloud Blog, Jun 12 2026).
A practical retrieval strategy is “filter, then traverse”:
- Filter by
typeandtags(for example,type: datasetplus a domain tag). - Follow links dataset → tables → metrics → runbooks.
OKF’s core promise is durability. Once your context lives in a knowledge bundle with consistent metadata and links, you can switch catalogs, search layers, and agent frameworks without rewriting the knowledge itself.
