FAQ — Open Knowledge Format (OKF)

Frequently asked questions, answered by a human who’s read the spec more times than is probably healthy.

What is OKF?

A folder of Markdown files that represents what your organization knows — tables, metrics, APIs, playbooks, whatever — in a way both humans and AI agents can understand without special tools.

Each .md file is a “concept.” YAML frontmatter at the top holds metadata. The structure is hierarchical and git-friendly. That’s mostly it.

Three mandatory rules:

Every .md (except index.md and log.md) needs parseable YAML frontmatter
Every frontmatter needs a non-empty type field
Reserved files (index.md, log.md) follow a defined structure

Everything else is up to you.

Who made it?

Google Cloud, published under Apache 2.0 in the GoogleCloudPlatform/knowledge-catalog repo.

Born inside the Knowledge Catalog (formerly Dataplex) world, but the spec is vendor-neutral. No Google Cloud required. Any org can adopt it.

Current version: 0.1 (Draft). Early, but usable today.

Do I need an SDK?

No. If you need an SDK to write Markdown files, we have bigger problems to discuss.

The spec literally says: “If you can cat a file, you can read OKF; if you can git clone a repo, you can ship it.”

To produce it: text editor. To consume it: eyes. To validate: check 3 rules.

Tooling exists (validators, generators). None of it is required.

How is it different from AGENTS.md?

Different jobs entirely.

AGENTS.md tells an agent how to behave. OKF tells an agent what exists in the world.

	AGENTS.md	OKF
Analogy	”Here’s how to act"	"Here’s what we know”
Scope	One repo	All org knowledge
Consumer	Coding agents	Any agent or human

They’re friends, not competitors. Your AGENTS.md can say “check the OKF bundle at /knowledge for domain context.”

How does it compare to Obsidian?

Same DNA (Markdown + frontmatter + links), different species.

Obsidian = personal knowledge tool. Wikilinks, graph view, plugins. Built for one human’s brain.

OKF = interchange spec. Built so Team A’s knowledge survives the trip to Team B (or Agent C) intact. Think: the difference between your personal notebook and a published reference manual.

Key differences: OKF uses standard Markdown links (not [[wikilinks]]), mandates a type field, has reserved files with defined structure, and is designed for programmatic consumption.

You can edit OKF bundles in Obsidian. They’ll coexist peacefully. Just don’t expect OKF to generate a pretty graph for you.

What about DESIGN.md?

DESIGN.md is a document. OKF is a format.

If you converted your DESIGN.md into OKF, it’d become one concept in a bundle — maybe type: Architecture Decision. OKF is the container; DESIGN.md is something that lives inside it.

That’s really all there is to say here.

Does it work with Claude/GPT/Gemini?

Yes. All of them. Any LLM that can read text — so, all of them — handles OKF natively.

Claude/Cursor: Drop the bundle in project context. Done.
GPT/ChatGPT: Upload the .md files or ZIP them.
Gemini: Natural fit via Knowledge Catalog, but works standalone too.
Any MCP agent: Serve the bundle as a resource.

Model agnosticism is a foundational requirement of the spec. No lock-in.

How do I validate a bundle?

Check 3 things:

Every non-reserved .md has parseable YAML frontmatter
Every frontmatter has a non-empty type field
Reserved files (index.md, log.md) follow their defined structure

That’s the whole spec compliance check. Here’s a one-liner if you want:

for f in $(find ./bundle -name "*.md" ! -name "index.md" ! -name "log.md"); do
  head -50 "$f" | grep -q "^type:" || echo "FAIL: $f missing type"
done

A client-side validator is coming at okf.md. But honestly, the bash loop above gets you 90% there.

Will OKF replace data catalogs?

No. The spec explicitly lists this as a non-goal.

Catalogs = platforms (UI, API, governance, lineage, permissions). OKF = export/exchange format.

Your catalog is the system of record. An OKF bundle is the portable snapshot you version in git, share across teams, or feed to an AI agent. Different layers, complementary roles.

Is it only for BigQuery?

The examples use BigQuery because that’s where it was born. The format doesn’t care.

type: PostgreSQL Table       # fine
type: API Endpoint           # fine
type: Runbook                # fine
type: Your Mom's Recipe      # technically valid

The type field is free-form. The optional resource field is a generic URI — point it at Grafana, Snowflake, Confluence, whatever. OKF documents any organizational knowledge, not just data assets.

How do I contribute?

Repo: GoogleCloudPlatform/knowledge-catalog
Open issues, submit PRs, contribute examples in samples/ and toolbox/
License: Apache 2.0

It’s v0.1 Draft — the best possible time to shape where it goes. There’s a CONTRIBUTING.md in the repo.

Do I need a backend?

No. A bundle is a folder of .md files.

Serve it with any static file server. Version it with git. Distribute it as a ZIP. The validator runs client-side in the browser. Zero databases, zero APIs, zero infra.

If you want to build on top of OKF (search, enrichment, a UI), that’s your call. But the format itself is pure filesystem. Refreshingly boring technology.

Does it work with git?

It works beautifully with git. In fact, git is the recommended distribution method.

Markdown = clean diffs
Commit history = who changed what concept and when
Branches = propose knowledge changes via PR
git clone = you have the entire bundle

The spec’s log.md is slightly redundant if you use git (commit log does the same job), but it’s there for when bundles travel without VCS history.

Git + OKF = organizational knowledge managed with the same practices we already use for code. Nothing new to learn.

What’s the future of OKF?

⚠️ Opinion — speculation ahead, not confirmed roadmap.

It’s v0.1 Draft. Google Cloud is testing the waters.

My read on what’s likely:

Short term: Knowledge Catalog integration, official CLI/validator, MCP support for serving bundles to agents.

Medium term: other providers adopt or create compatible formats, enrichment agents auto-generate bundles, maybe a public bundle registry.

My bet (opinion): OKF could become the “Markdown of organizational knowledge.” Same playbook — wins by being dead simple and universal. The timing is right: agents need structured context, the market is fragmented across proprietary solutions, and the spec has zero barriers to adoption.

The risk (also opinion): if Google doesn’t push cross-cloud adoption, it joins the graveyard of Google formats nobody asked for. But Apache 2.0 + vendor-neutral design help.

Practical advice: just start using it. The cost is literally zero — it’s Markdown files in a folder. Worst case, you have well-organized documentation.