JSON mit JSON Schema validieren

Worum es geht

Ein JSON Schema ist selbst ein JSON-Dokument mit Schlüsselwörtern wie type, properties, required, enum, minimum/maximum, minLength/maxLength, pattern, items und additionalProperties. Für jede grössere Sprache gibt es Validatoren; OpenAPI-Request- und -Response-Schemas sind ein Dialekt davon.

Warum es wichtig ist

Ein Schema ist ein Vertrag, den beide Seiten maschinell prüfen können und der Dokumentation erzeugt; es erkennt fehlende Felder, falsche Typen und Werte ausserhalb des zulässigen Bereichs, bevor die Geschäftslogik sie zu sehen bekommt, und liefert dem Client feldgenaue Fehler (Pfade).

So wird es angewendet

• Für jede Nutzlast, die eine Vertraünsgrenze überschreitet, zuerst das Schema schreiben; es nahe beim Code halten, der die Daten konsumiert.
• Bei Eingaben additionalProperties: false setzen (oder sie explizit auflisten), damit Tippfehler in Feldnamen und eingeschleuste Felder abgelehnt statt ignoriert werden.
• enum für abgeschlossene Wertemengen und Grenzwerte für Zahlen und Längen verwenden; format (date-time, uri) als Hinweis nutzen und dabei wissen, dass Validatoren sich darin unterscheiden, wie streng sie es durchsetzen.
• Beispiele in Tests validieren und in der Pipeline echte Antworten gegen das veröffentlichte Schema validieren.

Stolpersteine

Schemas können zu einer zweiten Implementierung der Geschäftsregeln heranwachsen; sie strukturell halten und Semantik im Code validieren. Draft-Versionen unterscheiden sich (2020-12 gegenüber draft-07); eine festlegen. Vom Schema erzeugte Fehler können Werte in Meldungen durchsickern lassen; vor der Rückgabe bereinigen.