Datenmodell

Ein Dokument ist ein JSON-Objekt mit blocks (Pflicht, Liste) und einem optionalen meta-Objekt; weitere Top-Level-Keys gibt es nicht. Der Vertrag ist JSON Schema v1 (schema/document-v1.json).

Aufbau eines Blocks

Jeder Block hat genau diese sieben Keys:

{
    "meta": {},
    "blocks": [
        {
            "id": "b_k3xf92ab",
            "type": "section",
            "enabled": true,
            "data": { "title": "Intro" },
            "settings": { "spacing_top": "lg", "width": "container" },
            "visibility": { "from": null, "until": "2026-12-31T23:59:59+00:00", "sites": null },
            "children": []
        }
    ]
}

Key	Anmerkungen
id	eindeutig pro Dokument, erzeugt als b_ + 8 zufällige alphanumerische Zeichen
type	Block-Handle passend zu ^[a-z0-9_-]+$
enabled	false = wird nie gerendert
data / settings	Inhaltsfelder / Präsentationseinstellungen (Objekte)
visibility	genau from, until (ISO 8601 oder null) und sites (Site-IDs oder null; eine nicht leere Liste verbirgt den Block auf unbekannten oder nicht gelisteten Sites)
children	verschachtelte Blöcke, für Container-Blöcke

• Versionen, Diffs und der Media-Index verwenden Block-IDs als Schlüssel. Dokumente oder Teilbäume mit ContentApi::duplicateDocument() / duplicateBlock() kopieren, damit jeder Block eine frische ID erhält.
• Die Verschachtelung ist auf 20 Ebenen begrenzt (ContentDocument::MAX_DEPTH); ein Feld kann sie mit maxDepth senken.

Normalisierung vs. strikte Validierung

• ContentDocument::normalize() repariert unsaubere Eingaben: fehlende IDs sowie fehlende Keys enabled, data, settings, children und visibility. Ungültiges JSON, ein fehlerhafter type, zu tiefe Verschachtelung und doppelte IDs landen in getErrors().
• DocumentValidator lehnt alles ab, was vom Vertrag abweicht: unerwartete oder fehlende Keys, falsche Typen, fehlerhafte visibility.

Jeder Schreibpfad (Formular-Widget über DocumentSaveGuard, Content::put(), REST PUT /document) normalisiert, validiert dann und lehnt das Dokument bei Fehlern aus einem der beiden Schritte ab. Unbekannte Block-Typen bleiben erhalten und werden nicht abgelehnt.