Validierung

Worum es geht

Im Hub hängst du Regeln an ein Feld: Pflichtfeld, nicht leer, Muster, Mindestwert und so weiter. CDMS prüft sie bei jedem Schreiben, also bei Create, PUT und PATCH. Ein Verstoß heißt Validierungsfehler, die Antwort ist 422.

Geprüft wird im System-Layer, gegen die Regeln aus den Metadaten des Modells. Die Annotationen wie @NotNull an den generierten Payload-Klassen beschreiben die Felder nur für die OpenAPI-Dokumentation.

Die Regeln und ihre Fehlerschlüssel

Ein paar Einzelheiten, die im Alltag zählen:

• @nullable heißt Pflichtfeld, auch wenn der Name das Gegenteil vermuten lässt.
• Jede Regel prüft nur ihren Werttyp: Länge und Muster nur Texte, Mindest- und Höchstwert nur Zahlen. Grenzen sind inklusive und dürfen Nachkommastellen haben (10.5).
• Bei einem reinen Datum (LocalDate) vergleicht CDMS mit heute. Heute ist weder Zukunft noch Vergangenheit, dafür gibt es @futureOrPresent und @pastOrPresent.
• Ein Wert null verletzt nur die Pflichtregeln. „Nicht leer“, Länge, Muster und Grenzen prüfen nur vorhandene Werte.
• Die Zeitregeln setzt du in den Metadaten des Modells (YAML), die Hub-Oberfläche bietet sie nicht an.

Wann welche Regel gilt: der Scope

Viele Regeln kannst du auf einen Geltungsbereich (Scope) beschränken:

Einen Scope haben „nicht leer“, Muster, Mindest- und Höchstwert (die beiden teilen sich einen) sowie die Zeitregeln. Beim Pflichtfeld steckt die Operation in der Regel-ID selbst: @nullable gilt immer, @notNullOnCreate und @notNullOnUpdate nur bei einer Operation. Die Länge aus der Feldeigenschaft gilt immer.

Maßgeblich ist die Operation je Objekt, nicht der Endpunkt. Schickst du in einem PATCH auf eine Firma einen neuen Mitarbeiter ohne id mit, wird dieser Mitarbeiter angelegt und mit den CREATE-Regeln geprüft.

Was geprüft wird: Create, PUT, PATCH

Das erklärt einen häufigen Unterschied: Ein PATCH mit einem einzigen Feld geht durch, derselbe Inhalt als PUT scheitert mit cannot-be-null an allen Pflichtfeldern, die du nicht mitgeschickt hast. Siehe PUT oder PATCH?

Der Ablauf: sammeln, Hooks, prüfen

Ein Before-Hook kann einen Verstoß also auflösen, etwa indem er ein fehlendes Pflichtfeld selbst setzt. After-Hooks laufen erst nach der Prüfung, ihre Änderungen prüft CDMS nicht mehr. Mehr zu Hooks unter Hooks: Arten und Zeitpunkte.

So sieht eine 422 aus

POST /api/rest/roster/create
{
  "data": {
    "name": "Frühschicht",
    "members": [
      { "name": "Erste" },
      { "name": "" },
      { "name": "Dritte" },
      { }
    ]
  },
  "response": ["id"]
}

{
  "error": "ApiValidationException",
  "messageKey": "validation-failed",
  "code": "422",
  "layer": "API",
  "violations": [
    { "field": "members[1].name", "rule": "cannot-be-empty" },
    { "field": "members[3].name", "rule": "cannot-be-null" }
  ]
}

So liest du den Pfad in field:

Der Index ist die Position in der Liste, so wie du sie geschickt hast. Hat ein Feld zwei Verstöße, stehen zwei Einträge in violations. Wie ein Client daraus markierte Formularfelder macht, steht unter Validierungsfehler ins Formular bringen.

Kindobjekte

Kindobjekte prüft CDMS mit, wenn es sie schreibt:

• Ein neues Kind ohne id wird angelegt und mit den CREATE-Regeln seines Modells geprüft.
• Ein Kind mit id, das über die Beziehung mitgeändert wird, wird mit den UPDATE-Regeln geprüft, bei PATCH nur die gesendeten Felder.
• Ein Kind, das nur per id verknüpft wird, prüft CDMS nicht. Es wird ja nicht verändert.

Scheitert ein Kind, wird auch der gültige Elternteil nicht gespeichert. Die ganze Anfrage ist eine Transaktion. Welche Beziehung Kinder anlegen oder ändern darf, steht unter Die vier Fälle beim verschachtelten Schreiben.

Eindeutig: die Datenbank prüft

Die Regel „eindeutig“ (@unique) wird zu einem Unique-Index in der Datenbank. CDMS prüft sie nicht vorher, sondern die Datenbank beim Speichern. Deshalb sieht die Antwort anders aus:

POST /api/rest/crm/customer/create
{ "data": { "number": "K-1001", "name": "Zweite GmbH" }, "response": ["id"] }

{
  "error": "DataIntegrityException",
  "messageKey": "already-exists",
  "code": "409",
  "layer": "database"
}

Entscheidungstabelle

„Richtiger Typ“ heißt: Text in einem Textfeld, Zahl in einem Zahlfeld, Zeitpunkte als yyyy-MM-dd HH:mm:ss, ein Enum-Wert, den das Modell kennt. Passt ein Wert nicht, prüft CDMS die Regeln gar nicht erst und antwortet mit 400 invalid-value und dem Pfad des Feldes:

Beim Einlesen von Create und PUT beginnt der Pfad bei der Wurzel des Körpers (data.amount). Bei PATCH beginnt er, wie in violations, innerhalb von data (dueOn).

Fallen

Wie es weitergeht

• Warum PUT andere Felder prüft als PATCH: PUT oder PATCH? Die null-Falle
• Felder, die beim Anlegen einen Wert bekommen: Defaultwerte
• Regeln im Hub setzen: Modellieren im Hub
• Die Fehlerform im Überblick: Antwortformat