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 tracks spec v0.2, runs locally, and needs no account. Google's four published reference bundles all pass it, three of them with zero errors and zero warnings under --strict. New to the format? Start with our complete guide to the Open Knowledge Format.
By WitsCode. Published June 16, 2026. Last updated August 12, 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 (section 11), a bundle conforms on three requirements. 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 follow their documented structure, which under v0.2 means index.md carries no frontmatter (the bundle root may declare only okf_version) and log.md uses ISO date headings. The suite codifies these as its six MUST rules, M1 through M6, and any one of them failing is an error.
TOLERATED(never a conformance failure)
The spec is deliberately lenient, and v0.2 says so explicitly. 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. The validator reports a dead link as rule S3, a warning, exactly as the spec intends. A bundle with a broken link is conformant in both modes; under --strict it simply does not clear the quality bar.
RECOMMENDED(the strict quality bar, separate from conformance)
Favor structural markdown (headings, lists, tables, fenced code). Include the recommended fields when they apply: title, description, resource, and tags. Since v0.2 the trust and lifecycle family is checked too, as rule S6: generated with by and at, verified entries, a status of draft, stable, or deprecated, and an absolute stale_after date. The legacy timestamp field still validates but generated supersedes it. These are the suite's six SHOULD rules, S1 through S6. Under --strict an unmet recommendation fails the run and sets strictClean to false in the report, but the conformance verdict itself never changes.
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# add the strict quality bar on top of the conformance verdict
node validator/okf-validate.mjs ./your-bundle --strict
# print only JSON, for piping
node validator/okf-validate.mjs ./your-bundle --jsonExit codes: 0 pass, 1 fail, 2 usage error. The report itself is written to okf-report.json inside the bundle directory.
A passing report looks like this:
{
"okfVersion": "0.2",
"declaredVersion": "0.2",
"bundle": "knowledge",
"strict": false,
"conformant": true,
"strictClean": true,
"pass": true,
"summary": { "concepts": 7, "reserved": 5, "links": 23, "errors": 0, "warnings": 0 },
"errors": [],
"warnings": []
}Since the v0.2 alignment the report separates concept documents from reserved files, echoes the okf_version the bundle declares, and reports conformant and strictClean as separate verdicts. For the worked example that ships with the suite, the human-readable summary reads 7 concepts, 5 reserved files, 23 links. The fixture suite behind it holds 14 bundles: 3 that must pass, including one exercising every v0.2 trust field, and 11 deliberately broken ones, from unparseable YAML to calendar dates that do not exist. CI runs all of them on every push. The checks go deeper than shape: frontmatter must actually parse as YAML rather than merely be delimited, sources entries are validated for structure, both v0.2 link forms resolve, and log.md date headings are checked against the real calendar.
Verified against Google's own reference bundles
A validator is only as credible as what it has been tested against, so the suite is run against the four reference bundles Google publishes with the spec: acme_retail, crypto_bitcoin, ga4, and stackoverflow. All four pass. Three of the four are clean even under --strict, with zero errors and zero warnings. And you do not have to take our word for any of it: one command, node tools/check-reference-bundles.mjs, clones Google's knowledge-catalog repository, validates every bundle in it, and prints the upstream commit it checked. The same check runs in CI as a canary, so if the spec or the reference bundles move, the suite knows before you do. That is what makes it a working check on the format rather than an opinion about it.
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. We also implement OKF end to end for client sites: an audit of what knowledge you have, a bundle built from it, and the validator wired into your CI so the bundle can never silently drift out of conformance.
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 inside the bundle directory that names every rule a file tripped, and exits 0 on pass or 1 on fail, so you can gate CI on it. Add --strict to layer a quality bar on top: unmet recommendations then fail the run, though the conformance verdict itself never changes.
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?
The OKF spec names conformance criteria in its text and Google ships reference 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 14 golden and deliberately-broken fixtures, and it is verified against Google's own reference bundles, which all pass. It is community tooling, not a Google product, and other community checkers exist too. More independent oracles are good for the format.
Who maintains the OKF conformance suite?
WitsCode, a product engineering studio, maintains the OKF conformance suite as an open-source project under the MIT license. The suite tracks the OKF specification (currently v0.2), runs on Node with zero dependencies, and accepts issues and contributions on GitHub. The Open Knowledge Format specification itself is published by Google Cloud; the suite is independent community tooling that validates bundles against it.
Does the validator support OKF v0.2?
Yes. The suite is aligned to OKF spec v0.2: it validates the reserved-file rules (index.md without frontmatter, ISO date headings in log.md), resolves the absolute bundle-relative link form the spec now recommends, checks the trust and lifecycle fields (generated, verified, status, stale_after) as recommendations, and understands the Attested Computation concept type. Bundles written against v0.1 still validate; the legacy timestamp field is accepted with generated superseding it.