JSON-Schema-Validierung Fehler bei API-Verträgen vor der Abgabe erkennen

Wenn Ihre API ein Feld zurückgibt, das in Ihrem Schema nicht existiert, oder eine Anfrage mit einem fehlenden erforderlichen Feld im Body akzeptiert, besteht ein Vertragsverstoß. Diese Fehler sind subtil, oft stumm und äußerst teuer, in der Produktion zu finden. Die Validierung mit JSON Schema erfasst sie früher – näher an der Stelle, wo sie eingeführt werden.

Dieser Leitfaden erklärt, wie JSON Schema funktioniert, welche Validatoren in Node.js, Python und AWS verwendet werden, und wie man sicherstellt, dass Ihr Schema nicht von der Realität abweicht.

Was JSON Schema ist

JSON Schema ist ein Vokabular zur Beschreibung der Struktur eines JSON-Dokuments. Es ist kein Code – es ist Metadaten. Sie schreiben ein Schema, das festlegt, wie ein gültiges JSON-Objekt aussieht, und validieren dann dieses Schema.

Das Schema selbst ist ein JSON-Dokument. Ein minimales Beispiel:

{
  "$schema": "https://json-schema.org/draft/2020-12",
  "type": "object",
  "properties": {
    "email": { "type": "string", "format": "email" },
    "age":   { "type": "integer", "minimum": 0 }
  },
  "required": ["email"]
}

Das ist alles. Geben Sie dieses an einen Validator mit einem beliebigen JSON-Payload, und Sie erhalten entweder eine Bestätigung oder eine strukturierte Liste mit Fehlern.

Die Kernwörter

Ein paar Wörter decken die meisten praktischen Validierungsbedarfe ab:

additionalProperties: false erhält besondere Beachtung. Es ist das Wort, das Ihr Schema strikt macht – jede Eigenschaft, die nicht im Schema deklariert ist, löst eine Validierungsfehler aus. Es ist standardmäßig deaktiviert, was bedeutet, dass die meisten Schemata schweigend ungültige Felder akzeptieren, es sei denn, Sie aktivieren es. properties verursacht einen Validierungsfehler. Es ist standardmäßig deaktiviert, was bedeutet, dass die meisten Schemata schweigend ungültige Felder akzeptieren, es sei denn, Sie aktivieren es.

Ein vollständiges Schema: Anfrage für die Benutzerregistrierung

Hier ist ein vollständiges JSON Schema für eine Anfrage an eine Registrierungs-Endpunkt. Dies ist das Schema, das Sie einmal schreiben und in jeder Schicht verwenden, die den Endpunkt berührt.

{
  "$schema": "https://json-schema.org/draft/2020-12",
  "title": "UserRegistration",
  "type": "object",
  "required": ["email", "password", "username"],
  "additionalProperties": false,
  "properties": {
    "email": {
      "type": "string",
      "format": "email"
    },
    "password": {
      "type": "string",
      "minLength": 8
    },
    "username": {
      "type": "string",
      "pattern": "^[a-zA-Z0-9_]{3,32}$"
    },
    "role": {
      "type": "string",
      "enum": ["user", "admin"],
      "default": "user"
    },
    "birthDate": {
      "type": "string",
      "format": "date"
    }
  }
}

Sie können dieses interaktiv gegen jedes Payload testen, indem Sie es mit dem IO Tools JSON Schema Validator vor der Integration in Ihr Code-Repository testen.

Validierung von API-Anfrage-Body

Express + AJV

AJV ist der schnellste JSON Schema-Validator für Node.js. Hier ist ein Express-Middleware, das die Anfrage-Body vor dem Erreichen des Handlers validiert:

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

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

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

// Usage
app.post("/register", validateBody(registrationSchema), registerHandler);

allErrors: true sagt AJV, alle Fehler im Dokument zu sammeln, anstatt beim ersten Fehler zu stoppen – nützlich, wenn Sie alle Validierungsfehler dem Client zurückgeben möchten.

in beiden der

In Python verwendet FastAPI unter der Haube Pydantic und generiert automatisch ein JSON Schema aus Ihren Typ-Annotationen. Wenn Sie mit einem externen JSON Schema arbeiten, das nicht aus Pydantic-Modellen stammt, jsonschema ist die Standardbibliothek:

from jsonschema import validate, ValidationError

schema = { ... }  # your schema dict

try:
    validate(instance=request_body, schema=schema)
except ValidationError as e:
    return {"error": e.message}, 400

AWS API Gateway

API Gateway unterstützt die Validierung von Anfrage-Body-Content standardmäßig. Sie definieren ein Modell (das ein JSON Schema-Dokument ist) und fügen es als REQUEST_BODY Validator an Ihre Methode an. Anfragen, die die Validierung nicht bestehen, werden auf Gateway-Ebene abgelehnt – bevor Ihre Lambda-Funktion überhaupt ausgeführt wird. Dadurch wird eine ganze Klasse von Handler-Fehlern verhindert und die Anzahl der Cold-Start-Aufrufe für ungültige Traffic reduziert.

Wiederverwendbare Schemata mit $ref und $defs

Wenn mehrere Schemata eine gemeinsame Struktur teilen – wie eine Adresse, ein Geldbetrag oder ein Pagination-Objekt – wird diese einmal in $defs definiert und mit $ref:

{
  "$defs": {
    "Address": {
      "type": "object",
      "required": ["street", "city", "country"],
      "properties": {
        "street": { "type": "string" },
        "city":   { "type": "string" },
        "country": { "type": "string", "pattern": "^[A-Z]{2}$" }
      }
    }
  },
  "type": "object",
  "properties": {
    "billingAddress":  { "$ref": "#/$defs/Address" },
    "shippingAddress": { "$ref": "#/$defs/Address" }
  }
}

verknüpft. In größeren Projekten leben Schemata in separaten Dateien und $ref verweist auf eine URI. Validatoren, die das $id Wort und URI-Resolutions unterstützen, können Schemata dynamisch oder aus einer Registry laden – AJV erledigt dies über addSchema().

Schema-Drift

Schema-Drift tritt auf, wenn das Schema und die tatsächliche API abweichen. Es ist häufiger, als man denkt: Das Schema wird einmal geschrieben, die API entwickelt sich, und niemand aktualisiert das Schema.

Die Symptome sind subtil. Ein Feld wird im Code umgenannt, aber nicht im Schema – die Validierung bleibt bestehen, weil additionalProperties nicht auf false gesetzt ist. Ein erforderliches Feld wird im praktischen Einsatz optional, weil der Code es nicht mehr prüft – das Schema sagt immer noch, dass es erforderlich ist, aber niemand bemerkt es, bis ein Client eine Anfrage ohne es sendet.

Die Erkennung von Drift erfordert, das Schema-Validierung als Test zu betrachten, nicht als Laufzeit-Prüfung. Einige Teams automatisieren dies mit Snapshot-Tests gegen echte Antwort-Protokolle. Andere führen den Schema-Validator in CI gegen eine Reihe von gespeicherten API-Anfragen aus. Der Punkt ist, dass das Schema regelmäßig getestet werden muss, nicht nur einmal deployt.

JSON Schema und OpenAPI

OpenAPI (früher Swagger) verwendet JSON Schema, um Anfragen- und Antwort-Body zu beschreiben, mit einigen Änderungen. In früheren Versionen (OpenAPI 2.0, 3.0) wurde ein Subset von JSON Schema mit Erweiterungen verwendet. OpenAPI 3.1 ist näher an JSON Schema Draft 2020-12 ausgerichtet, weshalb die Schemata größtenteils austauschbar sind.

Die praktische Unterschiede: OpenAPI umhüllt Schemata in ein größeres Dokument, das auch Pfade, Operationen, Authentifizierung und Server beschreibt. JSON Schema allein ist nur ein Validierungsvertrag. Wenn Sie eine schema-first-API entwickeln, können Sie das JSON Schema für jeden Endpunkt schreiben, es validieren und dann diese Schemata direkt in ein OpenAPI-Dokument übertragen.

Generierung von Schemata aus bestehenden Daten

Die manuelle Schreibweise von Schemata funktioniert gut für neue APIs. Bei bestehenden APIs mit nicht dokumentierter Funktionalität ist es oft schneller, ein Schema aus echten Payloads zu generieren und dann zu verfeinern.

Tools wie genson (Python) und generate-schema (Node.js) nehmen Beispiel-JSON-Objekte und erzeugen ein Entwurfsschema. Das generierte Schema ist fast immer zu liberal – alles wird optional, kein additionalProperties: false – aber es gibt Ihnen einen Ausgangspunkt. Sie fügen dann required, verfeinern type Definitionen und fügen enum Beschränkungen hinzu, wo Werte begrenzt sind.

Dieser Ansatz hilft auch, wenn Sie eine dritte Partei API mit keiner Schema-Dokumentation einbinden. Führen Sie mehrere Antworten durch einen Schema-Generator, fügen Sie die Ausgabe zusammen und haben ein funktionierendes Vertrags-Modell, das Sie validieren können.

Die Validierung mit JSON Schema gehört an jede Schicht, die strukturierte Daten akzeptiert – HTTP-Middleware, Consumer von Nachrichtenqueues, Datenbank-Schreibpfade. Je früher ein Vertragsverstoß auftritt, desto günstiger ist die Reparatur. Ein online-JSON-Schema-Validator erlaubt Ihnen, Schemata vor der Integration in eine Bibliothek an echten Payloads zu prototypisieren, was das richtige erste Schritt für jede Validierungsarbeit ist.

Das könnte Ihnen auch gefallen

Farbpalette-Generierung: Ein vollständiges Farbspektrum aus einem einzigen Hex-Wert erstellen

Mehr lesen "

Veröffentlicht am 12. Mai 2026

PDF-Signaturverifikation: Was Entwicklern bekannt ist

Mehr lesen "

Veröffentlicht am 10. Mai 2026

Markdown vs HTML: Wann jede für Dokumente, README-Dateien und APIs verwenden

Mehr lesen "

Veröffentlicht am 9. Mai 2026

UTM-Parameter: Wie man Marketing-Kampagnen ohne Spekulation verfolgt

Mehr lesen "

Veröffentlicht am 8. Mai 2026