JSON Schema: das Vertragsformat für deine API-Payloads

Was ist JSON Schema?

JSON Schema ist ein Format zur Beschreibung von JSON-Dokumenten. Es ist selbst JSON und beschreibt: welche Felder existieren dürfen, welche sind Pflicht, welche Typen sind erlaubt, welche Wertebereiche. Das aktuell empfohlene Spec-Level: Draft 2020-12.

Minimales Schema

Das einfachste mögliche Schema:

{ "type": "object" }

Es passt zu jedem Objekt. Mit mehr Struktur:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["name", "email"],
  "properties": {
    "name":  { "type": "string", "minLength": 1 },
    "email": { "type": "string", "format": "email" }
  },
  "additionalProperties": false
}

Damit passt jedes Objekt mit genau den Feldern name (string, nicht leer) und email (string, gültige E-Mail). Andere Felder werfen Fehler.

Die wichtigsten Top-Level-Keywords

Keyword	Bedeutung
$schema	Welche Draft-Version dieses Schema nutzt
$id	Eindeutige URI, unter der dieses Schema referenzierbar ist
type	Datentyp: string, number, integer, boolean, object, array, null
properties	(Bei type=object) Definition der Felder
required	(Bei type=object) Array von Feldnamen die Pflicht sind
items	(Bei type=array) Schema für die Elemente
$defs	Container für wiederverwendbare lokale Definitionen
$ref	JSON-Pointer zu einer Definition (lokal oder extern)

Type-System

JSON Schema kennt sieben primitive Typen:

• string: Text. Mit minLength, maxLength, pattern, format weiter constraint-bar.
• number: Beliebige Zahl. Mit minimum, maximum, multipleOf.
• integer: Ganze Zahl. Wichtig: nicht ein Subset von number, sondern eigener Typ.
• boolean: true oder false.
• null: nur der Wert null.
• object: JSON-Objekt. Mit properties, required, additionalProperties weiter beschrieben.
• array: JSON-Array. Mit items, minItems, maxItems, uniqueItems.

Ein Feld kann auch mehrere Typen erlauben: "type": ["string", "null"] für ein nullable String-Feld.

String-Constraints

{
  "type": "string",
  "minLength": 3,
  "maxLength": 50,
  "pattern": "^[a-zA-Z0-9_-]+$",
  "format": "email"
}

pattern ist ein ECMA-262-Regex als String. format ist semantisch - typische Werte: email, date-time, uri, uuid, ipv4, ipv6, hostname.

Number-Constraints

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

Array-Schemas

{
  "type": "array",
  "minItems": 1,
  "maxItems": 100,
  "uniqueItems": true,
  "items": {
    "type": "string",
    "minLength": 1
  }
}

Schema testen mit dem Tool oben

Im Validator oben kannst du Schema und JSON-Dokument seite-an-seite eingeben und sofort prüfen ob sie matchen. Wenn nicht, zeigt das Tool exakt welches Feld welche Constraint verletzt hat.