JSON Schema-Validierungsleitfaden: Überprüfen Sie Ihre Datenstruktur

Jede Anwendung, die Daten von externen Quellen empfängt, steht vor demselben grundlegenden Problem: Kann ich diesen Daten vertrauen? Ob API-Anforderungstexte, Konfigurationsdateien, Warteschlangennachrichten oder Datenimporte – nicht vertrauenswürdige Daten müssen validiert werden, bevor sie in das System gelangen. JSON Schema bietet eine standardisierte, sprachunabhängige Möglichkeit, zu definieren, wie gültige Daten aussehen, und eingehende Daten gegen diese Definition zu validieren. Dieser Leitfaden behandelt alles vom Schreiben Ihres ersten Schemas bis zu fortgeschrittenen Mustern für komplexe Validierung, mit praktischen Beispielen, die Sie sofort anwenden können.

Was ist JSON Schema?

JSON Schema ist ein JSON-Dokument, das die Struktur und Einschränkungen anderer JSON-Dokumente beschreibt. Es ist ein Vokabular, mit dem Sie JSON-Daten annotieren und validieren können, standardisiert von der Internet Engineering Task Force (IETF). JSON Schema definiert Regeln darüber, welche Felder vorhanden sein müssen, welchen Typ sie haben müssen, welche Werte akzeptabel sind und wie Objekte und Arrays strukturiert sein sollten.

Stellen Sie sich JSON Schema als Ihren Datenvertrag vor. So wie ein Datenbankschema die Spalten, Typen und Einschränkungen einer Tabelle definiert, definiert JSON Schema die Eigenschaften, Typen und Einschränkungen eines JSON-Dokuments. Alle JSON-Daten, die alle Einschränkungen in einem Schema erfüllen, werden als gültige Instanz bezeichnet, während Daten, die eine Einschränkung verletzen, ungültig sind.

Was JSON Schema nicht ist

• Kein Datenformat: JSON Schema definiert nicht, wie Daten serialisiert oder übertragen werden. Es beschreibt nur, wie gültige Daten aussehen.
• Kein Ersatz für Geschäftslogik: Die Schema-Validierung prüft die strukturelle Korrektheit (Typen, Formate, Bereiche). Komplexe Geschäftsregeln (wie „Ein Benutzer kann nicht mehr überweisen als sein Kontostand") gehören in den Anwendungscode.
• Kein Datenbankschema: Obwohl konzeptionell ähnlich, validiert JSON Schema JSON-Dokumente, nicht Datenbanktabellen. Sie können JSON Schema jedoch zusammen mit Datenbankeinschränkungen für eine mehrschichtige Verteidigung verwenden.

JSON Schema-Versionen

JSON Schema hat sich durch mehrere Entwürfe weiterentwickelt, wobei jeder Entwurf Funktionen hinzufügte und das Vokabular verfeinerte. Das Verständnis dieser Versionen hilft Ihnen, die richtige für Ihr Projekt auszuwählen und Kompatibilitätsprobleme zu vermeiden.

Ihr erstes Schema schreiben

Beginnen wir mit einem einfachen Beispiel: einem Schema für ein Benutzerobjekt mit Name, E-Mail und Alter.

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

Dieses Schema deklariert, dass ein gültiger Benutzer ein Objekt sein muss, bei dem name und email erforderliche String-Eigenschaften sind. Die Eigenschaft age ist optional, muss aber, wenn vorhanden, eine Ganzzahl zwischen 0 und 150 sein. additionalProperties: false verhindert alle Eigenschaften, die nicht im Schema definiert sind, und erkennt so Tippfehler und unerwartete Felder.

Referenz der Kernschlüsselwörter

JSON Schema bietet ein umfangreiches Vokabular an Schlüsselwörtern zur Definition von Einschränkungen. Hier sind die wichtigsten Schlüsselwörter, nach Kategorien geordnet.

Typ-Schlüsselwörter

Zahlenbeschränkungen

String-Beschränkungen

Objektbeschränkungen

Array-Beschränkungen

Gängige Schema-Muster

Reale Schemas erfordern oft Muster, die über einfache Typprüfungen hinausgehen. Hier sind die am häufigsten verwendeten Muster.

Bedingte Validierung mit if/then/else

Verwenden Sie bedingte Logik, um basierend auf Eigenschaftswerten unterschiedliche Einschränkungen anzuwenden. Beispielsweise erfordern Zahlungsobjekte je nach Zahlungsmethode unterschiedliche Felder.

{
    "type": "object",
    "properties": {
        "method": { "enum": ["credit_card", "bank_transfer"] },
        "card_number": { "type": "string" },
        "routing_number": { "type": "string" }
    },
    "required": ["method"],
    "if": {
        "properties": { "method": { "const": "credit_card" } }
    },
    "then": {
        "required": ["card_number"]
    },
    "else": {
        "required": ["routing_number"]
    }
}

Komposition mit allOf, anyOf, oneOf

Kompositionsschlüsselwörter ermöglichen es Ihnen, Schemas auf leistungsstarke Weise zu kombinieren:

• allOf: Daten müssen alle Unterschemata erfüllen. Wird verwendet, um mehrere Einschränkungen zu kombinieren oder wiederverwendbare Schema-Fragmente einzumischen.
• anyOf: Daten müssen mindestens ein Unterschema erfüllen. Wird für Union-Typen verwendet, bei denen mehrere Formen akzeptabel sind.
• oneOf: Daten müssen genau ein Unterschema erfüllen. Wird für sich gegenseitig ausschließende Alternativen verwendet.

{
    "oneOf": [
        {
            "type": "object",
            "properties": {
                "type": { "const": "email" },
                "address": { "type": "string", "format": "email" }
            },
            "required": ["type", "address"]
        },
        {
            "type": "object",
            "properties": {
                "type": { "const": "phone" },
                "number": { "type": "string", "pattern": "^\\+?[1-9]\\d{1,14}$" }
            },
            "required": ["type", "number"]
        }
    ]
}

Schema-Wiederverwendung mit $ref

Das Schlüsselwort $ref ermöglicht es Ihnen, Schemas zu referenzieren und wiederzuverwenden, wodurch Duplikate vermieden werden und Schemas wartbar bleiben. Sie können auf Schemas im selben Dokument oder in externen Dateien verweisen.

{
    "$id": "https://example.com/schemas/order.json",
    "type": "object",
    "properties": {
        "customer": { "$ref": "#/$defs/address" },
        "shipping": { "$ref": "#/$defs/address" },
        "billing": { "$ref": "#/$defs/address" },
        "items": {
            "type": "array",
            "items": { "$ref": "#/$defs/lineItem" },
            "minItems": 1
        }
    },
    "required": ["customer", "items"],
    "$defs": {
        "address": {
            "type": "object",
            "properties": {
                "street": { "type": "string" },
                "city": { "type": "string" },
                "zip": { "type": "string", "pattern": "^\\d{5}(-\\d{4})?$" },
                "country": { "type": "string", "minLength": 2, "maxLength": 2 }
            },
            "required": ["street", "city", "zip", "country"]
        },
        "lineItem": {
            "type": "object",
            "properties": {
                "product": { "type": "string" },
                "quantity": { "type": "integer", "minimum": 1 },
                "price": { "type": "number", "exclusiveMinimum": 0 }
            },
            "required": ["product", "quantity", "price"]
        }
    }
}

Nullable-Typen

In JSON Schema Draft 2020-12 werden nullable-Typen mit einem Typ-Array dargestellt, das "null" enthält:

{
    "type": ["string", "null"],
    "description": "An optional display name, or null if not set"
}

In früheren Entwürfen verwendete die OpenAPI-Spezifikation das Schlüsselwort nullable: true. Für Standard-JSON Schema verwenden Sie immer den Typ-Array-Ansatz.

Formatvalidierung

Das Schlüsselwort format bietet semantische Validierung über die Strukturprüfung hinaus. Es gibt an, dass ein String einem bekannten Format entsprechen muss. Zu den häufig unterstützten Formaten gehören:

JSON-Daten programmatisch validieren

Die Schema-Validierung ist am nützlichsten, wenn sie in den Anwendungscode integriert ist. Hier sind Beispiele mit beliebten Bibliotheken in verschiedenen Sprachen.

JavaScript mit Ajv

Ajv ist der am weitesten verbreitete JSON Schema-Validator für JavaScript. Es unterstützt alle Entwurfsversionen und bietet hervorragende Leistung durch JIT-Kompilierung von Schemas.

import Ajv from 'ajv';
import addFormats from 'ajv-formats';

const ajv = new Ajv();
addFormats(ajv);

const schema = {
    type: 'object',
    properties: {
        name: { type: 'string', minLength: 1 },
        email: { type: 'string', format: 'email' },
        age: { type: 'integer', minimum: 0 }
    },
    required: ['name', 'email'],
    additionalProperties: false
};

const validate = ajv.compile(schema);
const valid = validate({ name: 'Alice', email: 'alice@example.com', age: 30 });

if (!valid) {
    console.log(validate.errors);
    // [{ keyword: 'required', params: { missingProperty: 'email' }, ... }]
}

Python mit jsonschema

from jsonschema import validate, ValidationError

schema = {
    "type": "object",
    "properties": {
        "name": {"type": "string", "minLength": 1},
        "email": {"type": "string", "format": "email"},
        "age": {"type": "integer", "minimum": 0}
    },
    "required": ["name", "email"],
    "additionalProperties": False
}

try:
    validate(instance={"name": "Alice", "email": "alice@example.com"}, schema=schema)
except ValidationError as e:
    print(f"Validation failed: {e.message}")

API-Datenvalidierung mit JSON Schema

Eine der wertvollsten Anwendungen von JSON Schema ist die Validierung von API-Anforderungs- und Antwortdaten. Dies stellt sicher, dass Ihre API wohlgeformte Eingaben erhält und Daten im erwarteten Format zurückgibt, wodurch Fehler frühzeitig erkannt und klare Fehlermeldungen an Clients bereitgestellt werden.

Express.js-Middleware

import Ajv from 'ajv';

const ajv = new Ajv({ allErrors: true });

function validateBody(schema) {
    const validate = ajv.compile(schema);
    return (req, res, next) => {
        if (!validate(req.body)) {
            return res.status(400).json({
                error: 'Validation failed',
                details: validate.errors
            });
        }
        next();
    };
}

app.post('/api/users',
    validateBody({
        type: 'object',
        properties: {
            name: { type: 'string', minLength: 1, maxLength: 100 },
            email: { type: 'string', format: 'email' },
            role: { enum: ['admin', 'editor', 'viewer'] }
        },
        required: ['name', 'email'],
        additionalProperties: false
    }),
    (req, res) => {
        // req.body is guaranteed valid here
        createUser(req.body);
    }
);

OpenAPI und JSON Schema

OpenAPI (ehemals Swagger) verwendet eine Teilmenge von JSON Schema, um API-Anforderungs- und Antwortschemas zu definieren. Wenn Sie bereits OpenAPI verwenden, können Sie Schemas aus Ihrer API-Spezifikation extrahieren und für die Laufzeitvalidierung verwenden. Tools wie openapi-schema-validator und express-openapi-validator können diesen Prozess automatisieren und sicherstellen, dass Ihre API-Dokumentation und Validierungslogik stets synchron bleiben.

Best Practices

• Setzen Sie immer $schema: Fügen Sie das Schlüsselwort $schema ein, um die von Ihrem Schema verwendete Entwurfsversion zu deklarieren. Dies verhindert Mehrdeutigkeiten und stellt sicher, dass Validatoren Ihr Schema korrekt interpretieren.
• Verwenden Sie $id zur Schema-Identifikation: Das Schlüsselwort $id bietet einen eindeutigen Bezeichner für Ihr Schema und dient als Basis-URI für die Auflösung von $ref-Referenzen. Setzen Sie es immer, auch bei lokalen Schemas.
• Setzen Sie additionalProperties: false: Standardmäßig erlaubt JSON Schema beliebige zusätzliche Eigenschaften in Objekten. Das Setzen von additionalProperties: false erkennt Tippfehler und unerwartete Felder und macht Ihre Schemas strenger und Ihre API vorhersagbarer.
• Verwenden Sie $defs für wiederverwendbare Komponenten: Definieren Sie gängige Schemas in $defs und referenzieren Sie sie mit $ref. Dies reduziert Duplikate und macht Schemas wartbarer.
• Fügen Sie Beschreibungen hinzu: Jede Eigenschaft und jedes Schema sollte ein description-Feld haben. Dies dient sowohl als Dokumentation als auch als Hilfe für andere Entwickler, den Zweck und die Einschränkungen jedes Feldes zu verstehen.
• Validieren Sie an Systemgrenzen: Wenden Sie die Schema-Validierung an den Rändern Ihres Systems an: API-Endpunkte, Nachrichten-Consumer, Datenimport-Pipelines und Konfigurationslader. Validieren Sie keine Daten, die Ihr eigener Code bereits produziert hat und denen Sie vertrauen.
• Aktivieren Sie den strikten Modus im Validator: Konfigurieren Sie den Validator so, dass er unbekannte Schlüsselwörter ablehnt, die Formatvalidierung erzwingt und alle Fehler meldet, anstatt beim ersten Fehler anzuhalten. Dies erkennt mehr Probleme in einem einzigen Validierungsdurchlauf.
• Versionieren Sie Ihre Schemas: Fügen Sie die Schema-Version in die $id-URI ein (z. B. https://example.com/schemas/user/v2.json). Dies ermöglicht es Ihnen, Schemas weiterzuentwickeln, ohne bestehende Consumer zu beeinträchtigen.
• Testen Sie Ihre Schemas: Schreiben Sie Unit-Tests für Ihre Schemas mit gültigen und ungültigen Beispielen. Dies stellt sicher, dass Ihre Schemas die von Ihnen beabsichtigten Einschränkungen durchsetzen, und erkennt Regressionen bei Schema-Änderungen.
• Verwenden Sie format für die semantische Validierung: Bevorzugen Sie format: "email" gegenüber komplexen Regex-Mustern. Formate sind lesbarer, wartbarer und profitieren von gut getesteter Validierungslogik in Validator-Bibliotheken.