/spec/v0.2/

OKF v0.2 – die Spezifikation

OKF beschreibt Wissen als das, was ein Rechner ohnehin lesen kann: ein Ordner mit Markdown-Dateien, jede mit einem kleinen YAML-Kopf. Kein SDK, kein Schema-Register, keine Abfragesprache steht zwischen Ihnen und dem Inhalt. Sie lesen eine Datei mit cat, Sie geben ein Bundle mit git clone weiter.

Was „v0.2" hier bedeutet. OKF ist ein offenes, herstellerneutrales Basisformat; die maßgebliche Basis-Spec liegt im Repository von Google Cloud Platform und trägt dort aktuell die Nummer v0.1. v0.2 ist das Profil, das dieses Projekt implementiert: die Basis plus eine Schicht aus Herkunft, Prüfung und Lebenszyklus (generated, verified, status, stale_after, sources). Ein v0.2-Bundle bleibt für jeden Basis-Konsumenten lesbar – die Zusatzfelder sind optionale Erweiterungen, keine Bruchstellen.

1. Warum eine Vertrauensschicht

Die offene Basis stellt eine einzige harte Anforderung: ein Feld type. Das reicht, um Wissen portabel zu machen. Es reicht nicht, um Wissen belastbar zu machen. Wer eine KI-Antwort aus einem Konzept ableitet, will drei Dinge wissen: Wer hat das geschrieben? Hat es jemand geprüft? Ist es noch aktuell? Genau diese Fragen beantwortet die v0.2-Schicht, direkt im Frontmatter, maschinenlesbar.

2. Aufbau eines Bundles

Ein Bundle ist ein Verzeichnisbaum aus Markdown-Dateien. Die Struktur ist unabhängig von der Domäne. Zwei Dateinamen sind reserviert und dürfen nicht für Konzepte benutzt werden: index.md (Verzeichnisübersicht) und okf.md beziehungsweise README.md/INDEX.md (Sammel- und Aggregatdateien). Alles andere ist ein Konzept.

mein-bundle/
├── okf.md            # Aggregat-Index über das ganze Bundle (nicht als Konzept gelesen)
├── llms.txt          # Wegweiser für KI-Crawler
├── example.com/
│   ├── guides/
│   │   └── crawl-budget.md
│   └── analysis/
│       └── logfile-audit.md

Der OKF Knowledge Hub liest ein solches Bundle als .zip, als einzelne .md oder als bereits kompiliertes .json (ein Array von Konzeptobjekten). Beim Einlesen überspringt er Systemdateien und die Aggregatdateien okf.md, README.md, INDEX.md – sie sind Navigation, kein Wissen.

3. Das Konzeptdokument

Jedes Konzept ist eine UTF-8-Markdown-Datei aus zwei Teilen: dem YAML-Frontmatter und dem Markdown-Body. Der Frontmatter trägt die Felder, auf die Filter, Graph und Retrieval zugreifen; der Body trägt das eigentliche Wissen.

Ein vollständiges v0.2-Konzept sieht so aus:

---
type: "Guide"
title: "Crawl-Budget bei großen Websites"
description: "Wie Google das Crawl-Budget verteilt und woran man Verschwendung erkennt."
resource: "https://example.com/crawl-budget"
domain: "example.com"
category: "technical-seo"
tags: ["crawl-budget", "technical-seo", "indexierung"]
word_count: 1200
generated:
  by: "human:editor"
  at: "2026-07-29T20:40:00.000Z"
verified:
  - by: "human:editor"
    at: "2026-07-29T20:40:00.000Z"
status: "stable"
stale_after: "2027-07-29"
sources:
  - "https://example.com/crawl-budget"
---

# Was Crawl-Budget bedeutet

Der eigentliche Inhalt in Markdown …

Die Bedeutung jedes einzelnen Feldes, die YAML-Fallen und die Frage, welche Felder Pflicht und welche optional sind, stehen ausführlich im Frontmatter-Schema. Kurz: Für die offene Basis ist nur type verbindlich. Für ein belastbares v0.2-Bundle kommen die Provenance- und Lebenszyklusfelder dazu.

4. Die v0.2-Vertrauensfelder

Fünf Felder heben ein Bundle von portabel auf belastbar.

generated – wer oder was das Konzept erzeugt hat, mit Zeitstempel. by: "human:editor" oder etwa by: "agent:okf-pipeline". Trennt handgeschriebenes von maschinell erzeugtem Wissen. / who or what produced the concept, with a timestamp. Separates hand-written from machine-generated knowledge.
verified – eine Liste von Prüfungen, je mit by und at. Im Hub setzt „Als verifiziert markieren" genau diesen Eintrag, etwa human:eugen mit Datum. Eine Selbstauskunft, keine externe Zertifizierung. / a list of reviews, each with by and at. In the Hub, "Mark as verified" writes exactly this entry. A self-declaration, not external certification.
status – der Lebenszyklus, etwa stable, draft, deprecated. / the lifecycle state, e.g. stable, draft, deprecated.
stale_after – ein ISO-Datum, ab dem das Konzept als überprüfungsbedürftig gilt. Macht Aktualität zu einem Feld statt zu einer Vermutung. / an ISO date after which the concept is due for re-check. Turns freshness into a field rather than a guess.
sources – die externen Quellen, auf denen das Konzept beruht, als Liste. / the external sources the concept rests on, as a list.

Diese Felder sind optional. Ihr Fehlen macht ein Bundle nicht ungültig, es macht es nur weniger belastbar. Ein Konsument, der sie nicht kennt, soll sie erhalten und ignorieren, nicht ablehnen.

5. Cross-Linking

Konzepte verweisen mit normalen Markdown-Links aufeinander, empfohlen bundle-relativ mit führendem /:

Das ergänzt die Sicht aus [Logfile-Audit](/example.com/analysis/logfile-audit.md).

Ein Link behauptet eine Beziehung; welche, sagt der umgebende Text. Im Knowledge Graph des Hub werden zusätzlich gemeinsame Tags zu Ähnlichkeitskanten: Zwei Konzepte mit demselben Tag gelten als verwandt. Kaputte Links sind kein Fehler – sie dürfen auf noch nicht geschriebenes Wissen zeigen.

6. Konformanz

Konformanz kennt zwei Stufen.

Basis-konform ist ein Bundle, wenn jede nicht-reservierte .md-Datei einen parsebaren YAML-Frontmatter mit nicht-leerem type hat und die reservierten Dateien ihrer Struktur folgen. Das ist die harte Linie; sie entscheidet, ob ein Bundle überhaupt gelesen werden kann.

v0.2-vollständig ist ein Bundle darüber hinaus, wenn seine Konzepte die Provenance- und Lebenszyklusfelder tragen – generated, status, und wo sinnvoll verified, stale_after, sources. Das ist eine Qualitäts-, keine Gültigkeitsstufe. Wie sich beide Stufen praktisch prüfen lassen, steht auf der Validator-Seite.

Die tolerante Konsumtion bleibt Prinzip: Ein Konsument lehnt ein Bundle nicht wegen fehlender optionaler Felder, unbekannter Typwerte, zusätzlicher Schlüssel oder kaputter Links ab.

7. Versionierung

Versionen folgen dem Schema <major>.<minor>. Ein Minor-Sprung ergänzt rückwärtskompatibel – neue optionale Felder wie die Vertrauensschicht von v0.2. Ein Major-Sprung darf brechen. Ein Bundle darf seine Zielversion in der Wurzel-index.md deklarieren (okf_version: "0.2"), der einzigen Stelle, an der eine Index-Datei Frontmatter tragen darf. Wie Änderungen vorgeschlagen und aufgenommen werden, klärt die Governance-Seite.

Weiter im Thema

Feld für Feld erklärt das Frontmatter-Schema. Der Schnellstart baut ein erstes Bundle. Wer Bundles automatisch erzeugt, findet die reale Pipeline unter CLI und CI/CD.

Basis-Spec: OKF SPEC.md, v0.1 Draft. Die v0.2-Profilfelder (generated, verified, status, stale_after, sources) sind in der Pipeline und im Reader dieses Projekts implementiert. Stand 2. August 2026. / Base spec: OKF SPEC.md, v0.1 draft. The v0.2 profile fields are implemented in this project's pipeline and reader.