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 agent-readable markdown. WitsCode maintains a free, open-source conformance suite that checks any OKF bundle and tells you, pass or fail, whether it follows the spec. It runs locally and needs no account. New to the format? Start with our complete guide to the Open Knowledge Format.
By WitsCode. Published June 16, 2026. Last updated June 18, 2026.
What does OKF conformance mean?
An OKF bundle conforms when it satisfies three rules from the spec. Every non-reserved markdown file has a parseable YAML frontmatter block, every frontmatter block has a non-empty type field, and the reserved files index.md and log.md follow their structure when present. That is the entire bar. The spec is intentionally lenient: broken links, unknown type values, and missing optional fields are all tolerated, so conformance certifies that tools can interoperate, not that the knowledge is complete or correct.
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 the three things the spec requires, surfaces the things the spec tolerates as quality notes, and never claims the knowledge inside is correct.
MUST(required for conformance)
Per the OKF spec, a bundle conforms on three rules. Every non-reserved .md file contains a parseable YAML frontmatter block. Every frontmatter block has a non-empty type field. The reserved files index.md and log.md, when present, follow their documented structure. That is the whole conformance bar.
TOLERATED(never a conformance failure)
The spec is deliberately lenient. Consumers must tolerate broken cross-links, unknown type values, unknown frontmatter keys, missing optional fields, and missing index.md files. None of those make a bundle nonconformant, so the validator reports them as quality notes, not errors.
RECOMMENDED(good practice, optional under --strict)
Favor structural markdown (headings, lists, tables, fenced code). Include the recommended fields when they apply: title, description, resource, tags, and an ISO 8601 timestamp. Add a root index.md for progressive disclosure and a log.md for history. The validator surfaces these as warnings under --strict.
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": []
}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.
Sources: the Open Knowledge Format was announced by Google Cloud's Sam McVeety and Amir Hormati on June 2026. See the Google Cloud OKF announcement and the OKF specification (SPEC.md).
Frequently asked questions
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. 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?
Per the OKF spec, a bundle conforms on three rules: every non-reserved markdown file has a parseable YAML frontmatter block, every frontmatter block carries a non-empty type field, and the reserved files index.md and log.md follow their structure when present. The spec is deliberately lenient, so broken links, unknown type values, and missing optional fields are tolerated and never fail a bundle. A validator can still surface those as quality warnings 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 the spec's 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 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.