Open source by WitsCode
OKF Conformance: validate any Open Knowledge Format bundle
OKF conformance is whether a knowledge bundle correctly follows the Open Knowledge Format, Google Cloud's open spec for representing knowledge as portable, cross-linked markdown that AI agents read. WitsCode built an open-source conformance suite that checks any OKF bundle and tells you, pass or fail, whether it really speaks OKF. It is free, runs locally, and needs no account.
By WitsCode. Published June 16, 2026. Last updated June 17, 2026.
What is the Open Knowledge Format (OKF)?
The Open Knowledge Format (OKF) is an open specification from Google Cloud, published in June 2026, for representing knowledge as a directory of markdown files with YAML frontmatter. A bundle is just plain files: each concept is a .md file, the only required frontmatter field is type, and the format ships as v0.1 with no SDK, runtime, or database. The spec lives in Google Cloud's Knowledge Catalog repository, and the whole design goal is portability, so any tool or AI agent that can read files can read the knowledge. OKF is the file format agents read, not a service you call.
What does OKF conformance mean?
An OKF bundle conforms when it satisfies three things. Every non-reserved markdown file has a parsable YAML frontmatter block, every frontmatter block has a non-empty type field, and any reserved filenames follow the Open Knowledge Format spec. Conformance is about that shared structure, the wire that lets one tool's bundle be another tool's input. It does not judge whether the knowledge inside is correct, only whether the bundle is portable and machine-readable.
What OKF conformance checks
OKF is minimally opinionated by design, so conformance certifies the interoperability surface, the contract that lets one tool's output be another tool's input, and nothing past it. The suite checks structure, frontmatter, link resolution, reserved files, and the one required field. It does not check whether the knowledge itself is correct.
MUST(a violation is an error)
The bundle is a directory of .md concept files. Each file opens with a delimited YAML frontmatter block. Each has a non-empty type field. Every internal link to another .md file resolves. A file's path is its identity. The whole bundle reads with files only, no SDK, runtime, database, or network.
SHOULD(a violation is a warning, or an error under --strict)
A root index.md entry point. Folder index files that link their concepts. Single-purpose concepts. No orphan files. An ISO-8601 timestamp, a list of tags, and a URI resource when those optional fields are present. Synonyms merged into one concept.
MAY(allowed, never required)
Any additional frontmatter fields, log.md history files, and any body structure, headings, or tables.
Every finding names the rule id it tripped, so a report ties straight back to the written criteria.
How to validate an Open Knowledge Format (OKF) bundle
To validate a bundle, run the open-source OKF validator with Node 18 or newer and no dependencies. It prints a pass or fail summary, writes a machine-readable report, and returns an exit code you can use in CI.
node validator/okf-validate.mjs ./your-bundle# treat SHOULD recommendations as errors (stricter CI)
node validator/okf-validate.mjs ./your-bundle --strict
# print only JSON, for piping
node validator/okf-validate.mjs ./your-bundle --jsonExit codes: 0 conformant, 1 nonconformant, 2 usage error.
A passing report looks like this:
{
"okfVersion": "0.1",
"bundle": "knowledge",
"conformant": true,
"summary": { "concepts": 12, "links": 23, "errors": 0, "warnings": 0 },
"errors": [],
"warnings": []
}OKF vs llms.txt, AGENTS.md, and CLAUDE.md
OKF sits alongside a few conventions for making knowledge legible to AI, and it helps to know how it differs. llms.txt is a single file at a site's root that points crawlers at the pages worth reading. AGENTS.md and CLAUDE.md are instruction files that tell one coding agent how to work inside a repository. The Open Knowledge Format is broader: a whole directory of cross-linked, typed markdown concepts meant to be portable across tools, closer to the LLM wiki pattern Andrej Karpathy described, where an agent reads and maintains a structured knowledge base rather than a single hint file. llms.txt is a pointer, AGENTS.md and CLAUDE.md are instructions, and OKF is the knowledge itself.
Two oracles, and an honest ceiling
A single reference validator quietly becomes the spec: any bug in it counts as "conformant," and every tool inherits the same blind spot. So the suite keeps two independent oracles, the written criteria and the executable validator, and treats any disagreement between them as a defect in the spec, reconciled in the prose rather than silently patched in code. Every nonconformance found in the wild becomes a new test, so the suite grows from real failures.
Conformance buys a shared wire, not a shared mind.
That is the ceiling, stated plainly. The suite checks that tools can interoperate over the same files. It cannot certify that two producers mean the same thing by type: Metric, nor that the knowledge is correct. Those semantic differences are not a failure; they are the design.
Why WitsCode built this
WitsCode is a product engineering studio. We build websites, stores, and web applications for founders and teams, and a growing share of that work runs straight into AI agents and AI search. The Open Knowledge Format sits in exactly that territory, knowledge that agents can read. We build the open infrastructure our clients end up depending on, then publish it in the open. If you are shipping a web product, or you need a site that gets found in AI answers, that is the work we do.
Frequently asked questions
What is the Open Knowledge Format?
The Open Knowledge Format (OKF) is an open specification from Google Cloud, published in June 2026, for representing knowledge as a directory of markdown files with YAML frontmatter. Its only required field is type, and it needs no SDK, runtime, or database, so any tool that can read files can read an OKF bundle. It is the file format AI agents read, not a platform you log into.
What is OKF conformance?
OKF conformance is whether a knowledge bundle correctly follows the Open Knowledge Format, Google Cloud's open spec for representing knowledge as portable, cross-linked markdown that AI agents read. A bundle conforms when it meets the interoperability surface: it is a directory of .md concept files, each with a delimited YAML frontmatter block and a non-empty type, and every internal markdown link resolves. Conformance certifies a shared wire, not a shared mind: it checks that tools can interoperate, not that they agree on what each type means.
What are the OKF conformance rules?
A bundle conforms when every non-reserved markdown file has a parsable YAML frontmatter block, every frontmatter block carries a non-empty type field, and reserved filenames such as index.md follow the spec. Internal markdown links must resolve, and the whole bundle must read with files alone, no SDK or runtime. Those are the MUST rules; the spec adds SHOULD recommendations the validator can enforce under --strict.
How do I check if my OKF bundle is conformant?
Run the open-source OKF validator over your bundle: node validator/okf-validate.mjs ./your-bundle. It returns pass or fail, writes a machine-readable okf-report.json that names every rule a file tripped, and exits 0 when the bundle conforms or 1 when it does not, so you can gate CI on it. Add --strict to treat SHOULD-level recommendations as hard errors.
Is there an OKF validator?
Yes. WitsCode publishes a free, open-source OKF validator that checks any Open Knowledge Format bundle against the conformance rules and reports pass or fail. It runs locally on Node with no dependencies and no account, and the source is on GitHub under the MIT license.
Does OKF require an SDK or a runtime?
No. The Open Knowledge Format is plain markdown with YAML frontmatter, so an OKF bundle reads with files alone, with no SDK, runtime, database, or network call. That portability is the point: any tool that can read a directory of files can consume the knowledge.
How is OKF different from llms.txt?
llms.txt is a single file at a site's root that points crawlers at the pages worth reading. The Open Knowledge Format is a whole directory of cross-linked markdown concepts with typed frontmatter, and AGENTS.md and CLAUDE.md are instruction files for a specific agent or repo. They solve adjacent problems: llms.txt is a pointer, AGENTS.md and CLAUDE.md are instructions, and OKF is the portable knowledge itself.
Does OKF have an official conformance suite?
OKF v0.1 names conformance criteria in its spec text and ships sample bundles, but a criterion you read is not a suite you have to pass: prose describes, a suite certifies. This open-source suite formalizes the criteria as two independent oracles, written rules plus an executable validator, with golden and deliberately-broken fixtures, so conformant stops being self-reported. It is community tooling, not a Google product.
Is the Open Knowledge Format the same as the Open Knowledge Foundation?
No. They are unrelated and only share the abbreviation OKF. The Open Knowledge Format is Google Cloud's June 2026 file format for agent-readable knowledge, expressed as markdown bundles. The Open Knowledge Foundation is a long-standing non-profit promoting open data and open knowledge. This conformance suite is about the file format.