@jfomhover/okf-validator

⚠️ Experimental. Everything here may change without notice — flags, API, schema, package. Use it with that in mind.

Validate OKF v0.2 bundles — the format Google's knowledge-catalog uses. One tool, three ways to use it:

| | | |---|---| | 💻 CLI | npx okf-validate <path> — check bundles locally or in CI | | 🤖 Agent skill | teach opencode / Claude Code / Copilot to run it for you |

Checks OKF v0.2 conformance out of the box against a single versioned default JSON Schema — and honors your own custom schemas, per document, when you need stricter rules.

Quick start

npm install @jfomhover/okf-validator
npx okf-validate ./my-bundle

Requires Node.js ≥ 18. Output: errors: 0, warnings: 2 — warnings are informative, errors fail the run.

💻 CLI

Point it at a bundle, a folder of bundles, or a bundles/ corpus:

npx okf-validate ./my-bundle                                  # one bundle
npx okf-validate /path/to/knowledge-catalog/okf/bundles       # whole corpus
npx okf-validate --json ./my-bundle                           # machine-readable report
npx okf-validate --schemas ./my-schemas ./my-bundle           # resolve custom schema: paths

Exit codes: 0 conformant · 1 errors · 2 usage error. npx okf-validate --help lists all flags.

🤖 Agent skill

skills/okf-validate/ teaches a coding agent when to reach for the validator, how to install it, and what to run — then you can just say "validate this bundle" and let the agent take it from there.

It's standard Agent Skills (SKILL.md + frontmatter), so it works in opencode, Claude Code, Codex, GitHub Copilot CLI, Cursor, and 30+ other agents.

npx skills add jfomhover/okf-validator                              # all skills
npx skills add jfomhover/okf-validator --skill okf-validate         # just this one

Or drop skills/okf-validate/ into any discovery directory (.opencode/skills/, ~/.config/opencode/skills/, …). Full reference: skills/okf-validate/references/usage.md.

Custom schemas — your rules, per document

A concept's schema: frontmatter key chooses its validator:

• URL (https/http/file) → fetched and enforced for that document.
• Path (schema: revenue) + --schemas <dir> → resolved under that directory, with a .schema.json fallback.
• Anything else (okf_bundle, absent) → the bundled default schema applies.

The default schema is deliberately permissive: type is the only required field, the §5/§10 families are loosely typed, and unknown keys always pass (extensions are legal OKF). Strict per-type rules belong in a custom schema — the validator never judges what your schema requires.

Explicit bundle references

Use the validator-defined bundle: prefix when a frontmatter value must point to a file inside the current bundle:

graph:
  - relation: supports
    target: bundle:/concepts/example.md

source:
  extract: bundle:/extracts/example-page-03.md

bundle: references are resolved from the bundle root recursively through arrays and objects. Missing targets and paths that escape the bundle are errors. Ordinary strings, external URLs, and unprefixed resource descriptors keep their existing behavior.

What it checks

Errors — the bundle is not conformant:

• missing, malformed, or non-mapping frontmatter; missing or empty type
• missing index.md in a Markdown-containing directory
• reserved index.md/log.md violations (frontmatter where it isn't allowed, non-ISO date headings)
• a schema: reference that can't be loaded or resolved

Warnings — informative, never fatal:

• broken internal links, unresolvable path fields
• log.md frontmatter / entries not newest-first, misplaced or unsupported okf_version

Never flagged: unknown keys, unknown type values, absolute-URL links, #anchor links.

License

MIT © jfomhover