JSON-Schema-Validierung: Der komplette Leitfaden zu Schema-Drafts und Regeln

Was ist JSON Schema?

JSON Schema ist ein Vokabular zum Annotieren und Validieren von JSON-Dokumenten. Es definiert die Struktur, die Typen und die Einschränkungen, die ein JSON-Dokument erfüllen muss. Betrachten Sie es als Vertrag – das Schema beschreibt, wie gültige Daten aussehen, und Validatoren prüfen, ob ein Dokument diesem Vertrag entspricht.

JSON Schema wird selbst in JSON geschrieben, wodurch es maschinenlesbar und sprachunabhängig ist. Es wird von Validatoren in allen wichtigen Programmiersprachen unterstützt (JavaScript/Ajv, Python/jsonschema, Java/everit, Go/gojsonschema) und dient der API-Validierung, für Konfigurationsdateien und zur Formulargenerierung.

JSON-Schema-Grundlagen

Die zentralen Schlüsselwörter definieren die Form gültiger JSON-Dokumente.

• type – legt den erlaubten JSON-Typ fest: string, number, integer, boolean, object, array oder null. Die grundlegendste Einschränkung.
• properties und required – bei Objekten definiert 'properties' das Schema jedes Felds und 'required' listet auf, welche Felder vorhanden sein müssen. Felder, die nicht in 'required' stehen, sind standardmäßig optional.
• enum und const – 'enum' beschränkt einen Wert auf eine feste Auswahl, während 'const' ihn auf einen einzigen exakten Wert festlegt. Nützlich für Statusfelder, Kategorien und Konfigurationsoptionen.
• pattern und format – 'pattern' validiert Strings anhand eines regulären Ausdrucks. 'format' bietet semantische Validierung wie 'email', 'uri', 'date-time' und 'ipv4' ohne Regex.

Diese grundlegenden Schlüsselwörter decken die meisten Validierungsanforderungen ab. Ein einfaches Schema könnte einen Objekttyp mit erforderlichem 'name' (string) und optionalem 'age' (integer, minimum 0) definieren.

Erweiterte Schema-Funktionen

Für komplexe Validierungsanforderungen bietet JSON Schema Komposition, Referenzen und bedingte Logik.

• $ref-Referenzen – Schema-Definitionen wiederverwenden, indem man sie mit $ref referenziert. Zeigen Sie auf Definitionen innerhalb desselben Dokuments ($ref: #/$defs/Address) oder auf externe Dateien. Beseitigt Duplikate in großen Schemas.
• allOf / anyOf / oneOf – Kompositions-Schlüsselwörter, die mehrere Schemas kombinieren. 'allOf' verlangt, dass alle Teilschemas passen, 'anyOf' verlangt mindestens eines und 'oneOf' genau eines. Nützlich für polymorphe Typen.
• if / then / else – bedingte Schemas, die je nach Datenwert unterschiedliche Validierungsregeln anwenden. Beispiel: Wenn country 'US' ist, muss die Postleitzahl einem 5-stelligen Muster entsprechen, andernfalls ist jedes Format erlaubt.
• additionalProperties – steuert, ob ein Objekt Eigenschaften enthalten darf, die nicht in 'properties' aufgeführt sind. Auf false setzen für strikte Validierung oder auf ein Schema, um zusätzliche Eigenschaften einzuschränken.

Schema-Draft-Versionen

JSON Schema hat sich über mehrere Draft-Versionen weiterentwickelt, die jeweils neue Funktionen hinzufügen und bestehendes Verhalten verfeinern.

• Draft-04 – die erste weit verbreitete Version. Führte $ref, required als Array und grundlegende Validierungs-Schlüsselwörter ein. Wird noch in vielen Altsystemen und in OpenAPI 3.0 verwendet.
• Draft-06 – ergänzte das Schlüsselwort const, propertyNames, contains für Arrays sowie boolesche Schemas (true/false als gültige Schemas). Kleine, aber nützliche Ergänzungen.
• Draft-07 – ergänzte die bedingte Logik if/then/else, readOnly/writeOnly-Annotationen und Schlüsselwörter zur Inhaltskodierung. Die heute beliebteste Draft-Version.
• 2019-09 (Draft 2019-09) – umfassende Neustrukturierung. Führte $defs (als Ersatz für definitions), $anchor, unevaluatedProperties und ein Vokabularsystem ein. Besser für den Entwurf großer Schemas.
• 2020-12 (Draft 2020-12) – der aktuellste stabile Draft. Verfeinerte dynamische Referenzen, ergänzte prefixItems für die Tupel-Validierung (als Ersatz für items als Array) und verbesserte Ausgabeformate. Für neue Projekte empfohlen.

Häufige Anwendungsfälle

JSON Schema kommt überall dort zum Einsatz, wo JSON-Daten validiert oder dokumentiert werden müssen.

• API-Validierung – Request-Bodies und Query-Parameter in Express-/Fastify-Middleware gegen Schemas validieren. OpenAPI-/Swagger-Spezifikationen betten JSON Schema zur Definition des API-Vertrags ein.
• Konfigurationsvalidierung – Konfigurationsdateien der Anwendung (JSON, aus YAML nach JSON konvertiert) beim Start validieren. Fangen Sie Tippfehler und fehlende Felder ab, bevor sie Laufzeitfehler verursachen.
• Formulargenerierung – Tools wie react-jsonschema-form und vue-jsonschema-form erzeugen HTML-Formulare automatisch aus JSON-Schema-Definitionen, inklusive Validierungsregeln und UI-Widgets.
• Codegenerierung – TypeScript-Interfaces, Go-Structs oder Python-Dataclasses aus JSON-Schema-Definitionen generieren. Hält Typen mit API-Verträgen synchron.

Häufige Validierungsfehler

Bei der Validierung von JSON gegen ein Schema begegnen Ihnen am häufigsten diese Fehler.

• Typkonflikt – der Werttyp passt nicht zur 'type'-Einschränkung des Schemas. Typische Beispiele: string, wo eine Zahl erwartet wird, null für ein nicht nullbares Feld oder ein Objekt, wo ein Array verlangt wird.
• Fehlende Pflichtfelder – dem JSON-Objekt fehlt eine im 'required'-Array aufgeführte Eigenschaft. Validatoren melden, welches konkrete Feld fehlt.
• Muster-Fehlschlag – ein String-Wert entspricht nicht dem 'pattern'-Regex. Dies fängt häufig ungültige E-Mail-Formate, Telefonnummern oder eigene Kennungen ab, die dem erwarteten Muster nicht folgen.
• $ref-Auflösungsfehler – das Schema verweist über $ref auf ein anderes Schema, das nicht gefunden werden kann. Das passiert, wenn ein $defs-Eintrag fehlt, der Pfad falsch ist oder externe Schema-Dateien nicht erreichbar sind.

Häufig gestellte Fragen

Welchen JSON-Schema-Draft sollte ich für neue Projekte verwenden?

Verwenden Sie Draft 2020-12 für neue Projekte, sofern keine Einschränkungen bestehen. Er bietet die meisten Funktionen (prefixItems für Tupel, unevaluatedProperties, dynamische Referenzen) und die beste Spezifikationsqualität. Benötigen Sie Kompatibilität mit OpenAPI 3.0, verwenden Sie Draft-04. Brauchen Sie die breiteste Bibliotheksunterstützung, ist Draft-07 die sicherste Wahl – nahezu jeder Validator unterstützt ihn.

Wie verwende ich Schemas über mehrere Dateien hinweg wieder?

Verwenden Sie $ref, um Schemas per URI zu referenzieren. Für lokale Definitionen platzieren Sie wiederverwendbare Schemas unter $defs in derselben Datei und referenzieren sie mit $ref: '#/$defs/SchemaName'. Für dateiübergreifende Referenzen nutzen Sie relative URIs ($ref: './address.json') oder absolute URIs. Die meisten Validatoren unterstützen sowohl die lokale als auch die entfernte $ref-Auflösung.

Kann JSON Schema verschachtelte Objekte validieren?

Ja. Definieren Sie verschachtelte Schemas in den 'properties' des übergeordneten Objekts. Jede verschachtelte Eigenschaft kann eigene Typen, Pflichtfelder und Validierungsregeln haben. Für tief verschachtelte Strukturen verwenden Sie $ref, um das Schema lesbar zu halten. Für die Verschachtelungstiefe gibt es keine Grenze – der Validator validiert jede Ebene rekursiv.