okf validate

When to use it

• Before you trust a directory as a bundle: after cloning, after a big edit, before a PR merges.
• In CI, as the conformance gate. It exits 1 on a non-conformant bundle, 0 otherwise.
• As the first half of the quality question. validate answers "is it legal?"; okf lint answers "is it well curated?". The conformance model explains why those stay separate.

How it works

validate implements the spec's section 9 conformance definition exactly. Three conditions are hard errors, and the bundle is non-conformant until every one is fixed:

1. 9.1: every non-reserved file has a parseable YAML frontmatter block;
2. 9.2: every such block has a non-empty type;
3. 9.3: any index.md / log.md present follows the reserved-file rules: a nested index.md has no frontmatter, a root index.md carries only okf_version, and log.md date headings are ISO YYYY-MM-DD.

Everything the spec marks as soft guidance is a warning and never fails the bundle: missing recommended fields, non-list tags, an unparseable timestamp, and broken cross-links, which section 5.3 explicitly tells consumers to tolerate. Fix warnings when it is cheap. Never block on them.

Try it

okf validate docs/

OKF v0.1 conformance — docs
  concepts: 37   index.md: 10   log.md: 1
  ! warn  features/link-suggestions.md: cross-link target not found: `/graph-view.md` (tolerated under §5.3)
  ✓ conformant (33 warning(s))

For CI or an agent, --json emits the same result as compact single-line JSON:

okf validate docs/ --json

Pitfalls

• Do not expect broken links to fail validation. They are warnings by design; the spec forbids a validator from rejecting them. If dead links should block your pipeline, gate on okf lint --fail-on warn instead.
• A directory with zero frontmatter files is not "invalid", it is empty. Start with one concept file and validate again.
• Reserved files play by different rules. If validation fails on an index.md, the fix is usually removing frontmatter from a nested index or trimming a root index down to okf_version. The bundle anatomy page shows both shapes.