/spec/validator/

OKF validator

The validator answers two questions: can this bundle be read at all, and how dependable is it? It loads a .zip, a single .md, or a .json array and checks every file against two levels – base conformance and v0.2 completeness. The result cleanly separates what makes a bundle invalid from what would merely make it better.

This page describes what is checked and how to read the result. It is reference, not tool. The base rules can be walked through by hand before uploading a bundle.

Level 1 – base conformance (hard rules)

If a file violates one of these three rules, it is an error. The bundle is then not readably conformant.

Parsebarer Frontmatter. Jede Konzeptdatei beginnt mit einem gültigen YAML-Block zwischen zwei ----Zeilen. Ein Tab in der Einrückung, ein unmaskierter Doppelpunkt oder eine fehlende Abschlusszeile bricht die Regel. / Parseable frontmatter. Every concept file starts with a valid YAML block between two --- lines.
Nicht-leeres type. Jeder Frontmatter enthält ein type mit nicht-leerem Wert. / Non-empty type. Every frontmatter has a type with a non-empty value.
Reservierte Dateien werden nicht als Konzepte gelesen. Die Aggregatdateien okf.md, README.md, INDEX.md und die Verzeichnisübersicht index.md sind Navigation, kein Wissen – der Reader überspringt sie bewusst. / Reserved files are not read as concepts. The aggregate files okf.md, README.md, INDEX.md and the listing index.md are navigation, not knowledge – the reader skips them on purpose.

Level 1 asks for nothing more. A single file with type: "Reference" in its header is base-conformant.

Level 2 – v0.2 completeness (quality)

Level 2 checks whether concepts carry the trust and classification fields. A gap here is a warning, not an error – the spec explicitly requires consumers not to reject over missing optional fields.

Warnung / Warning	Warum sie zählt / Why it matters
Fehlende `description` / Missing `description`	Schwächere Such-Snippets; Retrieval verliert sein stärkstes Signal. / Weaker snippets; retrieval loses its strongest signal.
Keine `tags` / No `tags`	Konzept bleibt im Graphen isoliert, keine Ähnlichkeitskanten. / Isolated in the graph, no similarity edges.
Kein `generated` / No `generated`	Herkunft unklar – Mensch oder Agent? / Provenance unclear – human or agent?
Kein `status` / `stale_after`	Kein Lebenszyklus, keine Aktualitätsprüfung. / No lifecycle, no freshness check.
Keine `sources` / No `sources`	Aussagen ohne hinterlegten Beleg. / Claims without recorded evidence.
Inkonsistente `type`- oder Tag-Schreibweise	Zersplittert Filter und Kanten. / Splinters filters and edges.
Kaputter Cross-Link / Broken cross-link	Kann künftiges Wissen sein – oder ein Tippfehler. Prüfen. / May be future knowledge – or a typo. Check.

How to read a result

A run returns three blocks: errors (must go), warnings (a priority list for better metadata), and a summary with the number of concepts, the type values seen, and the share carrying the v0.2 trust fields.

Bundle: mein-wissen.zip        42 Konzepte / concepts
Fehler / errors:               0
Warnungen / warnings:          9
  - 5× fehlende description / missing description
  - 3× kein generated / no generated
  - 1× kaputter Link / broken link
Typen / types: Guide (28), Reference (9), Playbook (5)
v0.2-Vertrauensfelder / trust fields: 37/42
Status: BASIS-KONFORM · v0.2 teilweise / BASE-CONFORMANT · v0.2 partial

Zero errors means readably conformant. The 37/42 ratio shows how far the bundle reaches the dependability level.

Error classes and fixes

YAML nicht parsebar – fast immer Tabs, ein unmaskierter Doppelpunkt oder eine fehlende ----Zeile. / almost always tabs, an unescaped colon, or a missing --- line.
type fehlt oder leer – beschreibenden Wert ergänzen (Guide, Article, Reference). / add a descriptive value.
Verschachtelte Vertrauensfelder falsch eingerückt – generated/verified brauchen korrekt eingerückte Unterschlüssel by/at. / generated/verified need correctly indented by/at sub-keys.

Self-check before upload

In minutes without a tool: does every file have a --- block with a non-empty type? Do descriptions carry more than a repeat of the title? Are tags spelled consistently? And the question no validator asks: does the bundle contain passwords, API keys, or secrets that do not belong there?

Continue

The rules in detail are in the OKF v0.2 specification, the field reference in the frontmatter schema. For import warnings, troubleshooting helps.

Prüfstufen nach der OKF-v0.2-Konformanz dieses Projekts und dem Basis-Draft OKF SPEC.md §9. / Check levels per this project's OKF v0.2 conformance and the base draft OKF SPEC.md §9.