I kept seeing OKF mentioned in my feed. Every post said the same thing: “It’s just markdown with YAML frontmatter.” That’s technically true. It’s also like saying a city is “just buildings with addresses.” The address is the thing that matters.
So I did what I always do when something seems obvious: I built the same knowledge base twice. Once as plain markdown, once as OKF. Here’s what actually changed.
What OKF Actually Is
OKF (Open Knowledge Format) is a Google-led spec for representing structured knowledge as directories of markdown files. Each file has YAML frontmatter with a required type field and optional fields like title, tags, owner, timestamp, parent, and children.
That’s it. There’s no backend. No schema registry. No required service. Just a convention for what goes in the frontmatter of a markdown file so AI agents can reason about it.
The core insight: plain markdown is a document format. OKF is an artifact format. A document says “here’s what I wrote.” An artifact says “here’s what this is.”
The Concrete Comparison
Let’s say my team has a metric: avgDeliveryTime. In a plain markdown world, I’d create a file like this:
/notes/
avg-delivery-time.md
# Average Delivery Time
## Definition
The median time from order confirmation to doorstep, measured across all active delivery partners in the last 30 days.
## Owner
Platform Team
## SLA
< 28 minutes
## Last Updated
June 2026
## Related
- `delivery-partner-sla.md`
- `incident-log-2026-05.md`
---
We track this in our data warehouse under `metrics.delivery_avg_time`.
Query: `SELECT ...` (heavy SQL redacted for clarity)
That’s fine. It’s readable. But an AI agent reading this has to infer that this is a metric, that avgDeliveryTime is its identifier, that the SLA is a threshold, and that the SQL query is a data access pattern. It has to parse the prose to find the structure.
Now the same knowledge as an OKF artifact:
/knowledge/
metrics/
avg-delivery-time.md
---
type: metric
title: Average Delivery Time
owner: platform-team
timestamp: 2026-06-15T00:00:00Z
tags: [delivery, platform, sla, core-metric]
parent: delivery-platform
children:
- delivery-partner-sla
- incident-log-2026-05
sla:
threshold: 28
unit: minutes
direction: below
data:
warehouseTable: metrics.delivery_avg_time
query: "SELECT ..."
schema:
dimensions: [partner_id, region, tier]
measure: median_seconds
---
The agent doesn’t infer. It reads. type: metric tells it exactly what this is. sla.direction: below tells it the threshold is an upper bound, not a target. schema.dimensions tells it how to slice the data.
What Actually Changes
1. Navigation without full-text search
With plain markdown, the only way to find related knowledge is grep or a full-text index. With OKF, I can navigate by type. Show me every decision artifact. Show me every apiEndpoint under auth-service. Show me the full parent-child tree of delivery-platform.
That’s not possible with plain markdown without a convention you invent and maintain yourself.
2. Agents can query structure, not just content
A retrieval-augmented agent working from plain markdown can only do semantic search — find files that mention “delivery time.” An agent working from OKF can do structured queries: “Find all metric artifacts with sla.direction: above that haven’t been updated since Q1.” No full-text search can do that.
3. Consistency is enforced by convention, not discipline
With plain markdown, every author has their own conventions. One person writes Owner: Aniket. Another writes owner: aniket. A third doesn’t include an owner at all. An AI working from these files has to normalize all of that itself.
OKF doesn’t enforce this mechanically, but it defines the field names. owner is owner. type is type. The convention is shared, which means every agent and every author is working from the same map.
Where OKF Falls Short
I want to be honest about this, because the discourse around OKF has a hype problem.
OKF doesn’t solve knowledge graph construction. You still have to decide what parent and children relationships mean. You still have to maintain the hierarchy manually. The artifact types (metric, concept, playbook, decision, document, apiEndpoint) are just strings — there’s no schema enforcement. A file with type: metric is just a file with that string in its frontmatter.
It’s also not a replacement for a real knowledge graph database. It’s a serialization format. If you want graph queries, you still need something to parse the frontmatter and build the graph in memory. OKF is the input format, not the query engine.
And the types themselves are limited. Google’s initial set covers the basics, but organizations have knowledge that doesn’t fit neatly into metric, decision, or playbook. What’s the type for a runbook? A postmortem? A design doc? The spec is minimal by design, but that minimalism has real costs.
The Real Takeaway
OKF is not revolutionary. It’s a convention layer on top of markdown. But conventions matter — they’re the difference between a pile of documents and a navigable knowledge base.
The question isn’t whether OKF is better than plain markdown for a single file. It isn’t. Plain markdown is more readable for humans. The question is whether it’s better for a system — one where multiple agents, multiple authors, and multiple tools need to share and navigate knowledge at scale.
For that use case, the type field alone is worth the trade-off.