Custom Fields als Übergabevertrag

32 Schlüssel, 16 KiB und keine frei erfundenen Inhaltstypen: Die Grenzen der Custom Fields in Contentkit wirken klein. Für den Austausch zwischen Agenten und Veröffentlichung sind sie gerade deshalb brauchbar. Ein Agent kann Herkunft, Gültigkeit oder fachliche Kennungen strukturiert übergeben, ohne nebenbei ein zweites CMS-Datenmodell zu erfinden.

Teil 4 der Serie „Contentkit – Publishing für Maschinen“.

Text allein reicht für viele Veröffentlichungsaufgaben nicht. Eine Supportanleitung hat vielleicht einen verantwortlichen Dienst, eine betroffene Produktvariante und das Datum der letzten fachlichen Bestätigung. Ein Bericht trägt eine Abrechnungsperiode und eine Quellenkennung. Eine Sammlung von Architekturentscheidungen soll nach Status oder betroffenem System gruppierbar sein. Solche Angaben gehören nicht in zufällige Sätze, die jeder Abnehmer erneut herauslesen muss.

Contentkit nennt diese author-eigenen Zusatzfelder extra. Daneben gibt es fest definierte Frontmatter-Felder für Navigation, Versionierung, Zugriff und Beziehungen. Zusammen bilden sie einen Übergabevertrag: Der Agent liefert Inhalt plus überprüfbare Metadaten, Contentkit speichert beides in derselben unveränderlichen Revision.

Struktur mit absichtlich kleinem Umfang

Ein Dokument kann unter extra bis zu 32 Schlüssel enthalten. Namen beginnen mit einem Kleinbuchstaben und bestehen aus Kleinbuchstaben, Ziffern oder Unterstrichen. Werte dürfen Skalare, begrenzte Listen von Skalaren oder flache Maps sein. Insgesamt stehen 16 KiB zur Verfügung.

---
kind: page
layout: knowledge
title: Timeout during data export
locale: en
slug: data-export-timeout
translationKey: data-export-timeout
docKey: export-timeout
category: Troubleshooting
summary: Causes and verified steps for interrupted data exports.
extra:
  service: export-worker
  product_tiers: [business, enterprise]
  verified_at: 2026-07-15
  source:
    system: incident-review
    reference: INC-1842
---

Diese Angaben bleiben in ihren YAML-Typen erhalten. product_tiers ist eine Liste, source eine flache Map, verified_at ein skalierter Wert. In der Headless-API erscheinen sie unverändert in metadata. Contentkit versucht nicht, aus service eine universelle Fachlichkeit abzuleiten.

Die Begrenzung verhindert zwei typische Fehlentwicklungen. Erstens wird das Frontmatter nicht zur beliebig tiefen Ersatzdatenbank. Zweitens kann ein Agent keine umfangreiche, schwer prüfbare JSON-Struktur in einem Feld verstecken. Sobald ein Modell komplexe Objekte mit eigener Lebensdauer erzeugen soll, gehören diese in ein Fachsystem mit eigenem Vertrag.

Was Contentkit mit Zusatzfeldern macht

Standardmäßig sind extra-Felder Metadaten. Eine Website kann über settings.content.show_extra ausdrücklich erlauben, sie als Definitionsliste auf der Seite und als Aufzählung im Markdown-Zwilling sowie in llms-full.txt darzustellen. In JSON-LD und im Suchindex erscheinen sie nicht.

{
  "content": {
    "show_extra": true
  }
}

Diese Entscheidung ist sinnvoll, weil nicht jedes interne Ordnungsmerkmal in Suchmaschinen oder strukturierte Webdaten gehört. Eine interne Quellenkennung kann für einen Support-Agenten wichtig sein, ohne für Google ein eigenes Merkmal des Artikels zu werden. Auch die Volltextsuche soll nach dem hilfreichen Text suchen und nicht nach einer zufälligen Ticketnummer im Frontmatter.

Der Headless-Verbrauch bleibt trotzdem möglich. Ein autorisierter Dienst liest metadata.extra, filtert selbst nach service oder gleicht die Quellenkennung mit seinem Datenbestand ab. Contentkit speichert den Vertrag, übernimmt aber keine fachliche Interpretation.

flowchart LR
    A["Agent<br/>Text und Metadaten"] --> V["Contentkit<br/>validiert Grenzen"]
    V --> R["Unveränderliche<br/>Revision"]
    R --> H["HTML<br/>optional sichtbar"]
    R --> M["Markdown und<br/>llms-full.txt"]
    R --> J["JSON metadata.extra"]
    R -. nicht übernommen .-> S["Öffentlicher<br/>Suchindex"]
    R -. nicht übernommen .-> L["JSON-LD"]

Feste Felder, wo Contentkit Verantwortung trägt

Nicht jede Struktur ist ein Custom Field. Sobald Contentkit daraus Navigation, Route, Zugriff oder Darstellung ableitet, verwendet es kontrollierte Felder. Für Dokumentationsseiten sind das unter anderem docKey, docsVersion, parent, navTitle und navOrder. Eine Knowledge-Base-Seite kann category verwenden. Ein Changelog kennt releaseVersion und changeTypes. access bestimmt erlaubte Lesergruppen.

Diese Felder sind strenger, weil ein Fehler den Website-Stand beschädigen oder Inhalt sichtbar machen könnte. Contentkit prüft zum Beispiel, ob eine genannte Dokumentationsversion im Site-Preset existiert und ob die Elternseite in derselben Sprache, Version und Darstellungsart vorhanden ist.

Ein Agent sollte diese Trennung kennen:

• Felder, die Contentkit auswertet, folgen dem dokumentierten Frontmatter-Vertrag.
• extra trägt fachliche Metadaten, die Contentkit aufbewahrt und bei Bedarf darstellt.
• Größere Domänenobjekte bleiben im führenden Fachsystem und werden nur referenziert.

So bleibt erkennbar, welche Angabe tatsächlich Wirkung im Renderer hat. Ein frei erfundenes sidebar: true kann nicht unbemerkt ein neues Verhalten einschalten. Unbekannte gesteuerte Optionen werden abgelehnt oder haben keine definierte Wirkung, statt wie ein Plugin ausgeführt zu werden.

Beziehungen sind mehr als gemeinsame Tags

Posts können mit related bis zu acht Slugs derselben Sprache ausdrücklich als verwandte Beiträge nennen. Contentkit setzt diese authored Beziehungen an den Anfang des Bereichs mit verwandten Artikeln. Tag-Ähnlichkeit ergänzt die Liste auf bis zu drei sichtbare Empfehlungen.

related:
  - api-migration-v2
  - customer-export-runbook
tags: [Software, Architecture]

Eine fehlende Zielseite lässt den Build nicht scheitern. Contentkit verwirft den Verweis mit einer Warnung, weil der Beitrag noch unveröffentlicht sein kann. Das ist eine bewusst weichere Regel als bei einer fehlenden Elternseite: Eine Hierarchie wäre kaputt, eine Empfehlung ist lediglich unvollständig.

Für Agenten ist die explizite Beziehung wertvoll. Ein Modell kann aus dem Inhalt ableiten, dass eine Fehlerbehebung zur Migrationsanleitung gehört. Statt diese Beziehung nur in einem Satz zu verstecken, schreibt es sie in ein kontrolliertes Feld. Spätere Builds können sie reproduzieren.

Praxisbeispiel: Supportwissen übergeben

Ein Supportteam bearbeitet wiederkehrende Exportabbrüche. Das Ticketsystem enthält einzelne Fälle, die Betriebsplattform Messwerte und das Repository die freigegebene Fehlerbehebung. Ein Agent soll daraus kein neues Fachsystem bauen. Er soll einen bestätigten Wissensstand veröffentlichen.

Der Ablauf kann so aussehen: Der Agent findet alle geschlossenen Vorfälle mit derselben technischen Ursache. Er prüft, ob das freigegebene Runbook den beschriebenen Schritten entspricht. Dann erstellt er eine Hilfeportal-Seite mit dem eigentlichen Lösungsweg. Unter extra notiert er den betroffenen Dienst, die Produktvarianten, den fachlichen Prüfzeitpunkt und eine Referenz auf den bestätigten Vorfall.

Ein zweiter Agent liest später die veröffentlichten Seiten über die JSON-API. Bei einer neuen Supportanfrage filtert er nach dem betroffenen Dienst und prüft verified_at. Die Antwort an den Anwender verwendet ausschließlich den sichtbaren, freigegebenen Lösungstext. Ist die Bestätigung zu alt, verweist der Agent den Fall zur erneuten Prüfung, statt aus alten Tickets selbst eine Lösung zusammenzureimen.

Für Endanwender verbessert sich dadurch vor allem die Verlässlichkeit. Sie erhalten eine verständliche Anleitung, nicht den internen Datenbestand. Support-Mitarbeiter sehen zusätzlich, auf welcher bestätigten Grundlage sie beruht. Maschinen können dieselben Metadaten auswerten, ohne sie aus Prosa zu erraten.

Custom Fields sind kein Schema-Builder

Viele Headless-CMS bieten frei definierbare Inhaltstypen, verschachtelte Felder und eigene Redaktionsformulare. Das ist mächtig, bringt aber Schema-Migrationen, Formularlogik und Renderer-Abhängigkeiten mit sich. Contentkit wählt ausdrücklich ein leichteres Modell.

Eine wiederkehrende Sammlung entsteht als kind: post mit einem eigenen Tag und passenden extra-Feldern. Die Tag-Seite liefert Liste und Feed. Eine einmalige Darstellung bleibt kind: page. Es gibt keine frei definierbaren Kinds und keinen hochgeladenen Renderer für ein neues Feld.

Das ist keine allgemeine Antwort für jedes Content-Projekt. Ein Produktkatalog mit Varianten, Preisen, Lagerregeln und Transaktionen braucht ein eigenes Datenmodell. Für Dokumentation, Entscheidungen, Berichte, Wissensvisualisierung und redaktionelle Inhalte genügt häufig der kleinere Vertrag. Er lässt sich von Menschen lesen und von Agenten zuverlässig erzeugen.

Validierung hilft dem Agenten beim Korrigieren

Sprachmodelle erzeugen gern plausible Strukturen. Ohne Grenze wird aus source schnell eine verschachtelte Sammlung aus System, Autor, Prüflauf, Rohdaten und beliebigen Unterobjekten. Contentkit setzt dem feste Größen und Formen entgegen. Ein ungültiger Schlüssel oder eine zu große Struktur führt zu 422, bevor eine Revision akzeptiert wird.

type PublishedMetadata = {
  extra?: Record<string, unknown>;
  related_slugs?: string[];
  docs_version?: string;
  parent?: string;
};

Ein Agent kann diesen Fehler anhand des Vertrages korrigieren. Er muss keine visuelle Formularvalidierung interpretieren. Noch wichtiger: Er kann die Regeln vor dem Upload lokal abbilden und denselben Bestand vorab prüfen.

Die Validierung ersetzt keine fachliche Kontrolle. verified_at: 2026-07-15 kann formal gültig und trotzdem erfunden sein. Deshalb sollte die Agentenstrecke die Quelle für solche Werte belegen und im Review sichtbar machen. Contentkit garantiert die Form und die gemeinsame Revision, nicht die Wahrheit des Inhalts.

Metadaten beschleunigen Folgeprozesse

Sobald Zusatzangaben strukturiert vorliegen, müssen nachgelagerte Systeme weniger Text interpretieren. Eine mobile Anwendung kann nur Seiten für eine Produktvariante übernehmen. Ein Prüfagent kann alle veröffentlichten Anleitungen ermitteln, deren Bestätigung älter als sechs Monate ist. Eine Berichtsstrecke kann die Quellenkennung in den Nachweis übernehmen.

Diese Beschleunigung ist unspektakulär und dauerhaft. Sie hängt nicht davon ab, ob das nächste Modell bessere Zusammenfassungen schreibt. Sie entsteht aus einem stabilen Übergabevertrag. Text bleibt für Menschen, Metadaten tragen die wenigen Angaben, die Maschinen verlässlich unterscheiden müssen.

Konventionen gehören vor den ersten Agentenlauf

Die technische Freiheit von extra beantwortet nicht, welche Felder eine Organisation verwenden sollte. Ohne Konvention schreibt ein Agent verified_at, der nächste last_reviewed und ein dritter reviewDate. Formal sind alle Werte gültig, für Folgeprozesse entsteht dennoch keine verlässliche Struktur.

Ein kleines, versioniertes Feldverzeichnis schafft Abhilfe:

fields:
  service:
    type: string
    purpose: Stable service identifier from the catalog
  verified_at:
    type: date
    purpose: Date of the last domain-owner confirmation
  source:
    type: map
    keys: [system, reference]

Dieses Verzeichnis ist kein dynamischer Contentkit-Schema-Builder. Es ist eine Arbeitsregel für Agenten, lokale Validatoren und Reviews. Contentkit setzt weiterhin nur seine allgemeinen Größen- und Typgrenzen durch. Die fachliche Pipeline kann enger prüfen, ob service im Servicekatalog existiert und verified_at nicht in der Zukunft liegt.

Feldnamen sollten stabil, sachlich und unabhängig von der aktuellen Darstellung sein. card_color wäre ein schlechter fachlicher Vertrag, weil es ein Layoutdetail speichert. risk_level kann sinnvoll sein, wenn der Wert aus einem freigegebenen Risikomodell stammt und mehrere Abnehmer ihn verwenden.

Änderungen am Vertrag brauchen Migration

Auch kleine Metadatenkonventionen entwickeln sich. Wird product_tiers durch eine neue Produktklassifikation ersetzt, sollte ein Agent nicht still alte und neue Werte mischen. Zunächst liest eine Analyse die veröffentlichten Metadaten über die Read API. Danach erzeugt ein Migrationslauf neue Revisionen für betroffene Seiten. Eine Vorschau prüft Darstellung und Folgeprozesse, erst dann wird gemeinsam veröffentlicht.

Der alte Release behält seine damaligen Felder. Nachgelagerte Systeme können über Revisions- und Release-ID erkennen, welcher Vertrag galt. Diese Eigenschaft ist ein weiterer Grund, Custom Fields gemeinsam mit Markdown in der unveränderlichen Revision zu speichern statt sie in einer separaten, veränderlichen Tabelle nachzutragen.

Für kleine Bestände kann der Migrationsbericht eine einfache Markdown-Tabelle sein: Slug, alter Wert, neuer Wert und Quelle der Zuordnung. Bei großen Beständen übernimmt ein deterministischer Prozess die Umrechnung; der Agent erklärt Ausnahmen und erzeugt die reviewbare Zusammenfassung.

Review zeigt Metadaten und Text gemeinsam

Custom Fields dürfen im Review nicht hinter dem Fließtext verschwinden. Ein Agent sollte eine kompakte Änderungsliste erzeugen, die alte und neue Metadaten neben der Textänderung nennt. Eine neue Anleitung mit unverändertem verified_at kann verdächtig sein; eine geänderte Produktstufe kann dagegen mehr Anwender betreffen, obwohl der Text gleich bleibt.

Contentkit hilft, weil beides in derselben Revision liegt. Die Freigabe bezieht sich nicht auf einen Textstand und eine unabhängig veränderliche Metadatentabelle. Wird die Revision veröffentlicht, gelten beide zusammen. Ein Rollback stellt beide zusammen zurück.

Für besonders wirksame Felder kann die lokale Pipeline strengere Regeln verlangen. Ändert sich etwa risk_level von low auf critical, wird eine zusätzliche Freigabe erforderlich. Contentkit muss diese Fachregel nicht kennen. Es stellt die unveränderliche Eingabe und den kontrollierten Release bereit, auf denen der Workflow sie zuverlässig durchsetzen kann.

Fazit

Custom Fields machen Contentkit nicht zu einer beliebigen Inhaltsdatenbank. Sie ergänzen Markdown um einen kleinen, begrenzten Vertrag. Zusammen mit festen Feldern für Hierarchie, Version, Zugriff und Beziehungen kann ein Agent genau die Struktur übergeben, die der Release und nachgelagerte Systeme benötigen.

Der Nutzen liegt in der Trennung: Contentkit wertet nur kontrollierte Felder selbst aus, bewahrt extra unverändert auf und hält komplexe Fachmodelle außerhalb. Dadurch bleiben Dateien lesbar, Revisionen nachvollziehbar und Agenten korrigierbar. Für viele Wissens- und Veröffentlichungsabläufe ist weniger Schema mehr Verlässlichkeit.

Weiterführende Quellen

• Contentkit LLM-Gesamtdokumentation
• Contentkit Presets und Frontmatter
• Contentkit Architektur: abgeleitete und authored Daten

Wie fandest du diesen Beitrag?

Kommentare