JSON Schema: wie Schema-Validation API-Pipelines härtet

Was JSON Schema löst

JSON Schema beschreibt das erwartete Format eines JSON-Dokuments deklarativ. Damit kann man eingehende API-Payloads validieren, Konfigurationsdateien checken oder Code-Generatoren mit Typen versorgen - ohne die Validierungs-Logik manuell zu schreiben.

Die aktuelle Spec ist Draft 2020-12, finalisiert vom JSON-Schema-Komitee. Ältere Drafts (07, 2019-09) sind weit verbreitet - Library-Support für 2020-12 ist seit 2023 produktionsreif.

Minimal-Beispiel

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

Das Schema sagt: Top-Level muss ein Object sein, "email" und "age" sind Pflicht, "email" ein String im E-Mail-Format, "age" eine Zahl zwischen 0 und 150. Nichts anderes erlaubt.

Die wichtigsten Konstrukte

Keyword	Zweck
type	Basis-Typ: object, array, string, number, integer, boolean, null
required	Liste der Pflicht-Properties
properties	Schema pro Property
additionalProperties	false = nur deklarierte Keys erlaubt
enum	Erlaubte Werte als Aufzählung
pattern	Regex auf String-Inhalt
minimum / maximum	Number-Bereich
minLength / maxLength	String-Länge
items	Schema für Array-Elemente
$ref	Wiederverwendung anderer Schema-Definitionen

Ajv: der Standard-Validator in Node.js

Ajv ist die führende JSON-Schema-Library in JavaScript-Land. Vorteile:

• Schema wird zur Compile-Zeit in JavaScript-Funktion kompiliert
• ~31 Mikrosekunden pro Validierung - millionenfach pro Sekunde
• Strict-Mode bricht bei unbekannten Keywords ab - wichtig für Schema-Wartung
• Kompletter Draft 2020-12-Support seit Ajv 8.x

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

const ajv = new Ajv({ strict: true, allErrors: true });
addFormats(ajv);
const validate = ajv.compile(orderSchema);

if (!validate(payload)) {
  return reply(400, { errors: validate.errors });
}

Conditional Schemas

Mit if/then/else oder oneOf lassen sich konditionale Validierungen ausdrücken:

{
  "if":   { "properties": { "type": { "const": "card" } } },
  "then": { "required": ["cardNumber", "cvv"] },
  "else": { "required": ["iban"] }
}

Liest sich wie eine Programmiersprache, wird aber deklarativ ausgewertet.

Performance-Hinweise

1. Compile einmal, validate millionenfach. Nie ajv.compile() im Hot-Path aufrufen
2. strict-Mode an, sonst frisst Ajv Tippfehler in Keywords stillschweigend
3. allErrors aktivieren nur wenn man wirklich alle Fehler braucht - sonst ~15 % schneller
4. $ref vorsichtig - zirkuläre Refs sind erlaubt, aber langsamer

OpenAPI als Inkubator

OpenAPI 3.1 basiert direkt auf JSON Schema Draft 2020-12. Wer eine OpenAPI-Spec schreibt, kann die Schemas direkt mit Ajv validieren. Tools wie openapi-to-json-schema oder ajv-openapi automatisieren das.

Wann es sich nicht lohnt

Für einzelne Felder mit Trivial-Validierung (nur Required + Typ) ist ein 3-Zeilen-Check oft schneller hingeschrieben. JSON Schema entfaltet seinen Wert bei strukturierter Validierung über mehrere Felder, mit Refs und konditionaler Logik - also überall wo APIs wachsen.