JSON-Schema-Validierung: Der umfassende Leitfaden

JSON Schema ist ein Vokabular zur Annotation und Validierung von JSON-Dokumenten. Es bietet einen Vertrag für Ihre Daten — definiert, welche Form sie haben sollten, welche Typen akzeptabel sind und welche Felder erforderlich sind. Wenn Sie mit APIs, Konfigurationsdateien oder beliebigen strukturierten Daten arbeiten, ist JSON Schema ein unverzichtbares Werkzeug in Ihrem Arsenal.

Warum JSON Schema verwenden?

Ohne Validierung sind JSON-Daten eine Wundertüte. Sie könnten ein Altersfeld als String erhalten, eine fehlende E-Mail oder ein Datum im falschen Format. JSON Schema fängt diese Probleme an der Grenze ab, bevor schlechte Daten sich durch Ihr System ausbreiten.

Hauptvorteile:

API-Vertragsdurchsetzung: Request- und Response-Bodies automatisch validieren
Dokumentation: Das Schema dient als lebende Dokumentation für Ihre Datenstrukturen
Code-Generierung: Tools können Typen, Formulare und Datenbankschemata aus JSON Schema generieren
Testen: Test-Fixtures und Mock-Daten gegen das Schema validieren

Grundlegende Schema-Struktur

Jedes JSON Schema beginnt mit einigen Standard-Eigenschaften:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://example.com/user.schema.json",
  "title": "User",
  "description": "A registered user in the system",
  "type": "object",
  "properties": {
    "id": { "type": "integer", "minimum": 1 },
    "name": { "type": "string", "minLength": 1, "maxLength": 100 },
    "email": { "type": "string", "format": "email" },
    "age": { "type": "integer", "minimum": 0, "maximum": 150 }
  },
  "required": ["id", "name", "email"]
}

Verwenden Sie unseren JSON Formatter, um Ihre Schemas für bessere Lesbarkeit zu verschönern, bevor Sie sie mit Ihrem Team teilen.

Typeinschränkungen

JSON Schema unterstützt sechs primitive Typen:

Typ	Beschreibung	Beispiel
`string`	Textdaten	`"hello"`
`number`	Beliebiger numerischer Wert	`3.14`
`integer`	Nur ganze Zahlen	`42`
`boolean`	Wahr oder falsch	`true`
`array`	Geordnete Liste	`[1, 2, 3]`
`object`	Schlüssel-Wert-Paare	`{"key": "value"}`
`null`	Null-Wert	`null`

String-Einschränkungen

{
  "type": "string",
  "minLength": 1,
  "maxLength": 255,
  "pattern": "^[A-Za-z0-9]+$",
  "format": "email"
}

Eingebaute Formate umfassen: email, uri, date, date-time, ipv4, ipv6, uuid und hostname.

Zahlen-Einschränkungen

{
  "type": "number",
  "minimum": 0,
  "maximum": 100,
  "exclusiveMinimum": 0,
  "multipleOf": 0.01
}

Array-Validierung

Arrays können auf ihre Elemente, Länge und Einzigartigkeit validiert werden:

{
  "type": "array",
  "items": { "type": "string", "format": "email" },
  "minItems": 1,
  "maxItems": 10,
  "uniqueItems": true
}

Für Tupel-Validierung (Arrays fester Länge mit spezifischen Typen pro Position):

{
  "type": "array",
  "prefixItems": [
    { "type": "number" },
    { "type": "string" },
    { "type": "boolean" }
  ],
  "items": false
}

Objekt-Validierung

Objekte unterstützen Eigenschaftsvalidierung, Pflichtfelder und Kontrolle zusätzlicher Eigenschaften:

{
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "role": { "enum": ["admin", "editor", "viewer"] }
  },
  "required": ["name", "role"],
  "additionalProperties": false
}

Das Setzen von additionalProperties auf false ist ein strikter Modus, der alle Eigenschaften ablehnt, die nicht im Schema definiert sind. Dies ist besonders nützlich für APIs, bei denen Sie Tippfehler in Feldnamen erkennen möchten.

Kompositions-Schlüsselwörter

JSON Schema unterstützt die Kombination von Schemas mit logischen Operatoren:

allOf (UND)

Die Daten müssen gegen alle Unterschemas gültig sein:

{
  "allOf": [
    { "$ref": "#/$defs/baseUser" },
    { "properties": { "role": { "const": "admin" } } }
  ]
}

oneOf (XOR)

Die Daten müssen gegen genau eines der Unterschemas gültig sein:

{
  "oneOf": [
    { "properties": { "type": { "const": "email" }, "email": { "type": "string" } } },
    { "properties": { "type": { "const": "phone" }, "phone": { "type": "string" } } }
  ]
}

anyOf (ODER)

Die Daten müssen gegen mindestens eines der Unterschemas gültig sein.

Bedingte Validierung

Die Schlüsselwörter if/then/else ermöglichen bedingte Validierung:

{
  "type": "object",
  "properties": {
    "country": { "type": "string" },
    "postalCode": { "type": "string" }
  },
  "if": {
    "properties": { "country": { "const": "US" } }
  },
  "then": {
    "properties": { "postalCode": { "pattern": "^[0-9]{5}(-[0-9]{4})?$" } }
  },
  "else": {
    "properties": { "postalCode": { "pattern": "^[A-Z0-9 -]+$" } }
  }
}

Referenzen und Wiederverwendung

Verwenden Sie $ref, um wiederverwendbare Definitionen zu referenzieren:

{
  "$defs": {
    "address": {
      "type": "object",
      "properties": {
        "street": { "type": "string" },
        "city": { "type": "string" },
        "country": { "type": "string" }
      },
      "required": ["street", "city", "country"]
    }
  },
  "type": "object",
  "properties": {
    "billingAddress": { "$ref": "#/$defs/address" },
    "shippingAddress": { "$ref": "#/$defs/address" }
  }
}

Validierung in der Praxis

JavaScript (Ajv)

const Ajv = require('ajv');
const ajv = new Ajv();

const validate = ajv.compile(schema);
const valid = validate(data);
if (!valid) console.log(validate.errors);

Python (jsonschema)

from jsonschema import validate, ValidationError

try:
    validate(instance=data, schema=schema)
except ValidationError as e:
    print(f"Validation error: {e.message}")

Für schnelle Validierung ohne Einrichtung einer Entwicklungsumgebung fügen Sie Ihr JSON und Schema in unseren JSON Validator ein.

Praxisbeispiel: API-Antwort-Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "status": { "enum": ["success", "error"] },
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "name": { "type": "string" },
          "createdAt": { "type": "string", "format": "date-time" }
        },
        "required": ["id", "name"]
      }
    },
    "pagination": {
      "type": "object",
      "properties": {
        "page": { "type": "integer", "minimum": 1 },
        "perPage": { "type": "integer", "minimum": 1, "maximum": 100 },
        "total": { "type": "integer", "minimum": 0 }
      }
    }
  },
  "required": ["status", "data"]
}

FAQ

Was ist der Unterschied zwischen JSON Schema draft-07 und 2020-12?

Draft 2020-12 führte mehrere Verbesserungen ein: prefixItems ersetzte die Tupel-Form von items, $dynamicRef ermöglicht flexiblere Referenzen, und Vokabular-Unterstützung erlaubt benutzerdefinierte Erweiterungen. Für neue Projekte verwenden Sie 2020-12. Für die Kompatibilität mit älteren Tools wird draft-07 immer noch breit unterstützt.

Kann JSON Schema verschachteltes JSON innerhalb eines String-Feldes validieren?

Nein, nicht direkt. JSON Schema validiert die Struktur von geparsetem JSON. Wenn ein Feld einen JSON-String enthält, müssten Sie ihn zuerst parsen und separat validieren. Einige Validatoren bieten benutzerdefinierte Format-Validatoren an, die dies handhaben können, aber es ist nicht Teil des Standards.