Die Payload und ihre Prüfung

Worum es geht

Die Payload sind die Daten, die eine Vorlage in das Dokument einsetzt: Kundenname, Positionen, Datum. Deine Anwendung stellt sie zusammen. CRMS rechnet nicht, lädt nichts nach und folgt keinen Verweisen. Es setzt nur ein, was du schickst.

Darum prüft CRMS die Payload, bevor die Vorlage sie sieht. Es gibt zwei Prüfungen:

1. Die Struktur, für jede Payload: höchstens zwei Ebenen und nur einfache Werte.
2. Die deklarierten Felder: Eine Vorlage kann festlegen, welche Felder sie erwartet, mit Typ und ob sie Pflicht sind. CRMS prüft die Payload gegen diese Angaben.

Eine gültige Payload

{
  "title": "Begehung Halle 3",
  "approved": true,
  "tags": ["Brandschutz", "Fluchtwege"],
  "customer": { "name": "ACME", "city": "Köln", "phones": ["0221 1234"] },
  "items": [
    { "label": "Feuerlöscher geprüft", "amount": 480.00 },
    { "label": "Notausgang frei", "amount": 120.50 }
  ],
  "due": "2026-10-17"
}

Einfache Werte sind Text, Zahlen, true/false, Datumsangaben und Zeitpunkte. null ist überall erlaubt. Eingebettet darfst du auch Java-Datumswerte schicken: LocalDate, OffsetDateTime, ZonedDateTime, Instant. Über JSON kommen Datumsangaben als ISO-Text, siehe unten.

Beliebige Java-Objekte sind nicht erlaubt. Ein Objekt brächte seine Methoden in die Vorlage mit, und genau das soll die Sandbox verhindern.

Die Strukturregeln

Vor allem anderen schätzt CRMS die Größe der Payload. Ist sie größer als die Grenze der Installation (Standard 5 MiB, CODAMAI_CRMS_PAYLOAD_MAX_BYTES), kommt nur ein Verstoß zurück: Feld payload, Regel payload-too-large|<Grenze>. Die Grenze gilt auch für ein SVG in der Payload.

Die deklarierten Felder

Eine Revision einer Vorlage kann ihre Felder deklarieren. Jede Deklaration hat vier Teile:

Wie du Felder in einer Vorlage deklarierst, steht unter Wie eine Vorlage aufgebaut ist. Für die Prüfung gilt:

• Nicht deklarierte Werte sind erlaubt. Eine Vorlage darf mehr verwenden, als sie deklariert. Für sie gelten nur die Strukturregeln.
• DATE passt auf ein Datum oder auf ISO-Text wie "2026-10-17".
• DATETIME passt auf einen Zeitpunkt oder auf ISO-Text mit Zeitzonen-Versatz, etwa "2026-10-17T08:30:00+02:00" oder "…Z". Ohne Versatz ist es ein Verstoß.
• NUMBER passt auf jede Zahl, nicht auf Text wie "480".
• Bei items[].amount prüft CRMS jedes Element der Liste einzeln.

Wie Verstöße zurückkommen

CRMS sammelt alle Verstöße und antwortet einmal: 422 mit dem Schlüssel payload-rejected und der Liste violations. Jeder Verstoß nennt den Pfad des Werts und eine Regel. Ein Wert aus deiner Anfrage wird nie zurückgeschickt.

POST /crms/render
{
  "template": "audit-report", "format": "PDF", "mode": "PREVIEW",
  "data": {
    "items": [
      { "label": "Feuerlöscher", "amount": "480" },
      { "label": "Notausgang", "amount": 120.5,
        "detail": { "note": "zu tief" } }
    ],
    "due": "17.10.2026"
  }
}

HTTP 422
{
  "messageKey": "payload-rejected",
  "code": "422",
  "layer": "crms",
  "violations": [
    { "field": "items[1].detail", "rule": "depth-exceeded" },
    { "field": "items[0].amount", "rule": "type|number" },
    { "field": "due", "rule": "type|date" }
  ]
}

Die Strukturverstöße stehen vor den Verstößen gegen deklarierte Felder. Die Regel-Schlüssel übersetzt dein Frontend, siehe Fehler und Message Keys. Prüfen kannst du eine Payload auch ohne Rendern, mit POST /crms/render/validate, siehe Die Render-Anfrage.

Was die Vorlage danach sieht

Die Vorlage bekommt eine Kopie der geprüften Payload. Dabei macht CRMS aus jedem Feld, das als DATE oder DATETIME deklariert ist, einen echten Datumswert, auch wenn er als ISO-Text kam. So kann die Vorlage ihn in der Sprache und Zeitzone des Dokuments formatieren. Ein Kalenderdatum gilt als Mitternacht in der Zeitzone des Dokuments. Mehr unter Sprache und Zeitzone.

Fallen

Weiter

• Die Render-Anfrage
• Die Vorlagensprache
• Sprache und Zeitzone