/spec/frontmatter-schema/

Frontmatter schema and syntax

Frontmatter is the YAML block at the top of a concept, delimited above and below by ---. It holds the fields that filters, search, graph, and retrieval read. Everything below it is the body – the actual knowledge, in Markdown.

The logic is deliberately asymmetric: structured fields for the few things you query or filter; free Markdown for the prose people and models read. OKF v0.2 splits the fields into three groups – core, classification, trust.

All fields at a glance

Feld / Field	Gruppe / Group	Status	Bedeutung / Meaning
`type`	Kern / core	Pflicht / required	Art des Konzepts. Steuert Routing, Filter, Darstellung. / Kind of concept. Drives routing, filtering, presentation.
`title`	Kern / core	empfohlen	Lesbarer Anzeigename. / Human-readable display name.
`description`	Kern / core	empfohlen	Ein Satz, der das Konzept zusammenfasst; für Suche und Retrieval hoch gewichtet. / One sentence summarizing the concept; weighted highly in search and retrieval.
`resource`	Einordnung / classification	empfohlen	Kanonischer URI der Originalquelle. / Canonical URI of the original source.
`domain`	Einordnung / classification	empfohlen	Herkunft, z. B. `example.com`. / Origin, e.g. `example.com`.
`category`	Einordnung / classification	empfohlen	Primärer Themenbereich; erzeugt den Kategorie-Knoten im Graphen. / Primary topic area; creates the category hub in the graph.
`tags`	Einordnung / classification	empfohlen	Liste kurzer Strings; gemeinsame Tags erzeugen Ähnlichkeitskanten. / List of short strings; shared tags create similarity edges.
`word_count`	Einordnung / classification	empfohlen	Wortzahl; für Lesezeit und Sortierung. / Word count; for reading time and sorting.
`generated`	Vertrauen / trust	v0.2	Herkunft: `by` und `at`. / Provenance: `by` and `at`.
`verified`	Vertrauen / trust	v0.2	Liste von Prüfungen, je `by` und `at`. / List of reviews, each `by` and `at`.
`status`	Vertrauen / trust	v0.2	Lebenszyklus: `stable`, `draft`, `deprecated`. / Lifecycle: `stable`, `draft`, `deprecated`.
`stale_after`	Vertrauen / trust	v0.2	ISO-Datum, ab dem Prüfung fällig ist. / ISO date after which re-check is due.
`sources`	Vertrauen / trust	v0.2	Liste externer Belegquellen. / List of external supporting sources.

Only type is binding. Everything else improves quality and dependability but does not decide validity. If a field is missing on upload, the Hub fills it with a generic default: type becomes Article, domain becomes user-upload, category becomes general.

Minimal and full

The smallest conformant concept carries only type:

---
type: "Reference"
---

# HTTP-Statuscodes
…

The full v0.2 concept carries core, classification, and trust:

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

The core fields

type is the only required value: a short, self-explanatory string. This project's pipeline assigns four values automatically – Guide, Tool, CaseStudy, Article – from title and URL. They are not registered centrally; pick descriptive values and stay consistent within a bundle.

title is the visible name. description is the one sentence that makes the concept understandable without the full text. Write it to stand alone. Search and retrieval weight title and description well above the body – in the Hub specifically six and four times the body text.

The classification fields

resource names the canonical source URI, domain the origin. category is the primary assignment and creates the category hub in the graph; tags are additional cross-cutting markers, and shared tags create similarity edges between concepts. Keep spelling stable: geo and GEO are two tags to the machine. word_count feeds reading time and sorting.

Tags accept inline or block form – equivalent:

tags: ["crawl-budget", "technical-seo"]

tags:
  - crawl-budget
  - technical-seo

The trust fields – the heart of v0.2

These five fields separate a portable bundle from a dependable one.

generated records who or what produced the concept, with a timestamp:

generated:
  by: "human:editor"       # oder "agent:okf-pipeline"
  at: "2026-07-29T20:40:00.000Z"

verified is a list – a concept may have been reviewed more than once. In the Hub's reader, "Mark as verified" writes exactly one such entry with your profile, such as human:eugen. It is a self-declaration within your knowledge base, not external certification and not proof of factual accuracy.

verified:
  - by: "human:eugen"
    at: "2026-07-29T20:40:00.000Z"

status carries the lifecycle (stable, draft, deprecated). stale_after sets an ISO date after which the concept becomes due for review – freshness as a field, not a guess. sources lists the external evidence the concept rests on.

status: "stable"
stale_after: "2027-07-29"
sources:
  - "https://example.com/crawl-budget"

Custom fields

Producers may set arbitrary additional keys; consumers should preserve rather than reject them. That is exactly how domain, category, and word_count came to be as profile extensions beyond the open base. A bundle with extra fields stays fully readable to any other OKF consumer.

YAML syntax: the common traps

Nur Leerzeichen einrücken, nie Tabs. Ein Tab macht den Block unparsebar – und ein unparsebarer Block ist nicht konform. / Indent with spaces only, never tabs. A tab makes the block unparseable – and an unparseable block is not conformant.
Werte mit Doppelpunkt in Anführungszeichen. description: "Umsatz: brutto vs. netto". / Quote values containing a colon.
Verschachtelte Felder korrekt einrücken. generated und verified haben Unterschlüssel; die Einrückung entscheidet über die Struktur. / Indent nested fields correctly. generated and verified have sub-keys; indentation decides the structure.
Die abschließende ----Zeile nicht vergessen. / Don't forget the closing --- line.

Continue

The rule set is in the OKF v0.2 specification. The quick start builds a bundle from these fields, the prompt templates let a model produce the frontmatter, and the validator page checks it.

Feldsemantik nach der OKF-v0.2-Pipeline dieses Projekts (transform_to_okf.py) und dem Basis-Draft OKF SPEC.md. / Field semantics per this project's OKF v0.2 pipeline and the base draft OKF SPEC.md.