/spec/validator/

OKF-Validator

Der Validator beantwortet zwei Fragen: Kann dieses Bundle überhaupt gelesen werden, und wie belastbar ist es? Er lädt eine .zip, eine einzelne .md oder ein .json-Array und prüft jede Datei gegen zwei Stufen – Basis-Konformanz und v0.2-Vollständigkeit. Das Ergebnis trennt sauber, was ein Bundle ungültig macht, von dem, was es nur besser machen würde.

Diese Seite beschreibt, was geprüft wird und wie das Ergebnis zu lesen ist. Sie ist Referenz, kein Werkzeug. Die Basisregeln lassen sich auch von Hand nachvollziehen, bevor Sie ein Bundle hochladen.

Stufe 1 – Basis-Konformanz (harte Regeln)

Verletzt eine Datei eine dieser drei Regeln, ist das ein Fehler. Das Bundle ist dann nicht lesbar konform.

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.

Mehr verlangt Stufe 1 nicht. Eine einzige Datei mit type: "Reference" im Kopf ist basiskonform.

Stufe 2 – v0.2-Vollständigkeit (Qualität)

Stufe 2 prüft, ob die Konzepte die Vertrauens- und Einordnungsfelder tragen. Fehlt hier etwas, ist das eine Warnung, kein Fehler – die Spec verlangt ausdrücklich, dass Konsumenten wegen fehlender optionaler Felder nichts ablehnen.

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.

Wie ein Ergebnis zu lesen ist

Ein Lauf liefert drei Blöcke: Fehler (müssen weg), Warnungen (Prioritätenliste für bessere Metadaten) und eine Zusammenfassung mit Zahl der Konzepte, getroffenen Typwerten und dem Anteil, der die v0.2-Vertrauensfelder trägt.

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

Null Fehler heißt lesbar konform. Der Bruch 37/42 zeigt, wie weit das Bundle die Belastbarkeitsstufe erreicht.

Fehlerklassen und Behebung

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.

Vor dem Upload selbst prüfen

In Minuten ohne Werkzeug: Hat jede Datei einen ----Block mit nicht-leerem type? Tragen Beschreibungen mehr als eine Wiederholung des Titels? Sind Tags konsistent geschrieben? Und die Frage, die kein Validator stellt: Enthält das Bundle Passwörter, API-Schlüssel oder Geheimnisse, die dort nicht hingehören?

Weiter im Thema

Die Regeln im Detail stehen in der OKF-v0.2-Spezifikation, die Feldreferenz im Frontmatter-Schema. Bei Import-Warnungen hilft die Fehlerbehebung.

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.