JSON Schema verstehen: Daten wie ein Profi validieren

Hatten Sie schon einmal einen Bug, bei dem Ihre API "42" (einen String) statt 42 (eine Zahl) zurückgab und alles Nachfolgende kaputtging? Oder jemand schickte eine Anfrage ohne ein Pflichtfeld und Ihre App stürzte ab, anstatt eine hilfreiche Fehlermeldung zurückzugeben? JSON Schema existiert genau, um solche Probleme zu verhindern.

Stellen Sie es sich als Bauplan für Ihre JSON-Daten vor — es beschreibt, welche Form die Daten haben sollen, und fängt alles ab, was nicht passt.

Wie JSON Schema aussieht

JSON Schema wird selbst in JSON geschrieben (ziemlich meta, oder?). Hier ist ein einfaches Schema für ein Benutzer-Objekt:

Das sagt: „Ich erwarte ein Objekt mit einem erforderlichen name (nicht-leerer String) und einer email (gültiges E-Mail-Format), plus einem optionalen age (Ganzzahl zwischen 0 und 150)." Wenn jemand {"name": "", "email": "not-an-email"} sendet, fängt der Validator beide Probleme ab.

Schemas Schritt für Schritt erstellen

Beginnen Sie mit dem Typ. Jedes Schema beginnt mit "type": object, array, string, number, integer, boolean oder null.

Fügen Sie Einschränkungen hinzu. Für Strings: minLength, maxLength, pattern (Regex). Für Zahlen: minimum, maximum, multipleOf. Für Arrays: minItems, maxItems, uniqueItems. Der offizielle JSON Schema-Guide hat die vollständige Liste.

Markieren Sie Pflichtfelder. Verwenden Sie das "required"-Array auf Objektebene. Listen Sie nur Felder auf, die wirklich vorhanden sein müssen — machen Sie nicht alles zum Pflichtfeld, es sei denn, Sie meinen es ernst.

Definieren Sie verschachtelte Objekte. Verschachteln Sie einfach Schema-Definitionen innerhalb von "properties". Hier ist ein Benutzer mit einer Adresse:

Das pattern bei der Postleitzahl? Es stellt sicher, dass nur 5-stellige US-Postleitzahlen akzeptiert werden. Solche praxisnahe Validierung verhindert, dass Datenmüll in Ihre Datenbank gelangt.

Warum Sie das wirklich nutzen sollten

API-Validierung: Validieren Sie eingehende Request-Bodies am Rand Ihrer API. Schlechte Daten werden mit klaren Fehlermeldungen abgelehnt, bevor sie Ihre Geschäftslogik berühren. Die meisten Frameworks unterstützen das — Ajv für JavaScript ist blitzschnell.

Konfigurationsvalidierung: Validieren Sie Konfigurationsdateien beim App-Start. Scheitern Sie früh mit einer klaren Meldung wie „Ihrer Konfiguration fehlt das database.host-Feld" statt einer kryptischen Null-Pointer-Exception 5 Minuten später.

Dokumentation: JSON Schema dient gleichzeitig als lebendige Dokumentation. Tools wie Swagger UI generieren API-Docs direkt aus Schemas.

Codegenerierung: Generieren Sie TypeScript-Interfaces, Go-Structs oder Python-Dataclasses aus Ihrem Schema. Einmal schreiben, überall verwenden.

Testing: Validieren Sie API-Antworten in Ihrer Testsuite, um Regressionen automatisch zu erkennen.

In 30 Sekunden loslegen

Der schnellste Einstieg? Generieren Sie ein Schema aus vorhandenen JSON-Daten. Fügen Sie eine JSON-Beispielantwort in unseren JSON Schema Generator ein — er analysiert die Daten und erstellt ein Schema, das Sie verfeinern können. Testen Sie es dann mit unserem JSON Schema Validator gegen echte Daten.

Sie können auch programmatisch validieren. Hier ein schnelles Node.js-Beispiel mit Ajv:

Für Python gibt es die jsonschema-Bibliothek. Für Java gibt es everit-json-schema. Praktisch jede Sprache hat solide Unterstützung — schauen Sie sich die vollständige Liste der Implementierungen an.

Fortgeschrittene Schema-Features, die Sie kennen sollten

Sobald Sie die Grundlagen beherrschen, bietet JSON Schema einige mächtige Features, die komplexe Validierung ermöglichen.

oneOf, anyOf, allOf — Schemas kombinieren:

Manchmal kann ein Feld einen von mehreren Typen haben. Zum Beispiel könnte eine API entweder eine String-ID oder eine numerische ID akzeptieren:

Dieses Schema akzeptiert sowohl {"id": "PRD-1234"} als auch {"id": 42}, lehnt aber {"id": -1} oder {"id": "invalid"} ab.

$ref — Wiederverwendbare Schema-Definitionen:

Wenn Ihre Schemas wachsen, möchten Sie dieselben Definitionen nicht wiederholen. Das Schlüsselwort $ref ermöglicht es, auf gemeinsame Definitionen zu verweisen:

Jetzt verwenden sowohl billing_address als auch shipping_address exakt dieselben Validierungsregeln. Ändern Sie die address-Definition einmal, und beide Felder werden aktualisiert. Das ist essenziell, um große Schemas wartbar zu halten.

additionalProperties — Ihre Objekte absichern:

Standardmäßig erlaubt JSON Schema zusätzliche Eigenschaften, die nicht in properties aufgeführt sind. Das ist oft NICHT das, was Sie wollen — unerwartete Felder könnten auf einen Client-Bug oder eine Versions-Inkompatibilität hinweisen. Setzen Sie "additionalProperties": false, um unbekannte Felder abzulehnen:

Mit diesem Schema würde {"name": "Alice", "email": "[email protected]", "admin": true} abgelehnt werden, weil admin keine definierte Eigenschaft ist.

Häufige JSON Schema-Fehler

Auch erfahrene Entwickler machen diese Fehler beim Schreiben von Schemas:

1. Vergessen, dass required auf Objektebene steht, nicht auf Eigenschaftsebene. Das ist falsch:

Der richtige Weg ist:

2. "type": "number" verwenden, wenn man "type": "integer" meint. Der Typ number akzeptiert Dezimalzahlen wie 3.14, während integer nur ganze Zahlen akzeptiert. Wenn Ihr Feld ein Zähler oder eine ID ist, verwenden Sie integer.

3. format für gängige Muster nicht angeben. JSON Schema hat eingebaute Format-Validatoren für email, uri, date-time, ipv4, ipv6, uuid und mehr. Nutzen Sie diese, anstatt komplexe Regex-Muster zu schreiben.

4. Alles als Pflichtfeld markieren. Markieren Sie Felder nur als erforderlich, wenn sie wirklich vorhanden sein müssen. Ein zu restriktives Schema macht die API-Evolution schwieriger — ein neues optionales Feld hinzuzufügen ist eine nicht-brechende Änderung, aber diese Flexibilität geht verloren, wenn alles Pflicht ist.

Praxisbeispiel: E-Commerce-Produkt-Schema

Schauen wir uns ein praktisches Schema an, das Sie für eine Produkt-API verwenden könnten:

Dieses Schema stellt sicher, dass jedes Produkt einen Namen (1-200 Zeichen), einen positiven Preis und eine Kategorie aus einer festen Liste hat. Tags sind optional, müssen aber eindeutige Strings mit maximal 10 Einträgen sein. Das enum-Schlüsselwort ist unglaublich nützlich für Felder, die nur bestimmte Werte akzeptieren sollen.

JSON Schema-Versionen: Welchen Draft verwenden

JSON Schema hat mehrere Drafts durchlaufen — jeder als IETF Internet-Draft veröffentlicht — und das kann für Einsteiger verwirrend sein. Hier ein schneller Überblick:

Für neue Projekte verwenden Sie 2020-12 (den aktuellsten). Wenn Sie mit einer bestehenden Codebasis arbeiten, prüfen Sie, welchen Draft Ihr Validator unterstützt. Die meisten modernen Validatoren wie Ajv unterstützen Draft 7 und neuer.

JSON Schema in Ihren Workflow integrieren

Hier ist ein praktischer Ansatz, um JSON Schema-Validierung zu einer Express.js-API hinzuzufügen:

Dieses Muster gibt Ihnen automatische Request-Validierung mit klaren Fehlermeldungen. Die Option allErrors: true stellt sicher, dass alle Validierungsfehler auf einmal gemeldet werden, nicht nur der erste.

Probieren Sie es selbst aus

Bereit, Schema-Validierung in Ihr Projekt einzubauen? Starten Sie mit diesen Tools:

• JSON Schema Generator — Fügen Sie beliebige JSON-Daten ein und lassen Sie automatisch ein Schema generieren. Perfekt zum Bootstrappen von Schemas aus Beispiel-API-Antworten.
• JSON Schema Validator — Testen Sie Ihr Schema gegen echte Daten, um sicherzustellen, dass es das Richtige abfängt und das Erlaubte durchlässt.
• JSON Validator — Überprüfen Sie schnell, ob Ihr JSON syntaktisch gültig ist, bevor Sie sich um Schema-Validierung kümmern.

JSON Schema mag wie zusätzlicher Aufwand erscheinen, aber es zahlt sich vielfach aus, indem es Bugs an der Grenze Ihres Systems abfängt, anstatt tief in Ihrer Geschäftslogik.