Eugen Ullrich / OKF Hub
/spec/v0.2/

OKF v0.2 – the specification

OKF describes knowledge as something a machine can already read: a folder of Markdown files, each with a small YAML header. No SDK, no schema registry, no query language stands between you and the content. You read a file with cat; you ship a bundle with git clone.

What "v0.2" means here. OKF is an open, vendor-neutral base format; the authoritative base spec lives in the Google Cloud Platform repository and currently carries the number v0.1. v0.2 is the profile this project implements: the base plus a layer of provenance, review, and lifecycle (generated, verified, status, stale_after, sources). A v0.2 bundle stays readable to any base consumer – the extra fields are optional extensions, not breaking points.

1. Why a trust layer

The open base makes a single hard demand: a type field. That is enough to make knowledge portable. It is not enough to make knowledge dependable. Anyone deriving an AI answer from a concept wants to know three things: who wrote this, did anyone check it, is it still current? The v0.2 layer answers exactly those questions, in the frontmatter, machine-readable.

2. Bundle structure

A bundle is a directory tree of Markdown files. The structure is independent of the domain. Two filename groups are reserved and must not be used for concepts: index.md (directory listing) and the aggregate files okf.md, README.md, INDEX.md. Everything else is a concept.

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

The OKF Knowledge Hub reads such a bundle as .zip, as a single .md, or as pre-compiled .json (an array of concept objects). On read it skips system files and the aggregate files okf.md, README.md, INDEX.md – they are navigation, not knowledge.

3. The concept document

Every concept is a UTF-8 Markdown file in two parts: the YAML frontmatter and the Markdown body. The frontmatter carries the fields that filters, graph, and retrieval read; the body carries the actual knowledge.

A full v0.2 concept looks like this:

---
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 …

The meaning of each field, the YAML traps, and which fields are required versus optional are detailed in the frontmatter schema. In short: for the open base, only type is binding. For a dependable v0.2 bundle, the provenance and lifecycle fields join it.

4. The v0.2 trust fields

Five fields lift a bundle from portable to dependable.

  • 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.

These fields are optional. Their absence does not make a bundle invalid; it only makes it less dependable. A consumer that does not know them should preserve and ignore them, not reject.

5. Cross-linking

Concepts reference each other with ordinary Markdown links, preferably bundle-relative with a leading /:

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

A link asserts a relationship; the prose says which. In the Hub's Knowledge Graph, shared tags additionally become similarity edges: two concepts with the same tag count as related. Broken links are not an error – they may point to not-yet-written knowledge.

6. Conformance

Conformance has two levels.

A bundle is base-conformant if every non-reserved .md file has a parseable YAML frontmatter with a non-empty type, and reserved files follow their structure. That is the hard line; it decides whether a bundle can be read at all.

A bundle is v0.2-complete on top of that if its concepts carry the provenance and lifecycle fields – generated, status, and where sensible verified, stale_after, sources. That is a quality level, not a validity level. How to check both levels in practice is on the validator page.

Tolerant consumption stays the principle: a consumer does not reject a bundle for missing optional fields, unknown type values, extra keys, or broken links.

7. Versioning

Versions follow the <major>.<minor> scheme. A minor bump adds backward-compatibly – new optional fields like the v0.2 trust layer. A major bump may break. A bundle may declare its target version in the root index.md (okf_version: "0.2"), the only place an index file may carry frontmatter. How changes are proposed and adopted is on the governance page.

Continue

Field by field is explained in the frontmatter schema. The quick start builds a first bundle. To generate bundles automatically, the real pipeline is under CLI and 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.