HandyTools Hub

← Alle Anleitungen

JSON Schema erklärt: Validierung, Typen und die Schlüsselwörter, die die eigentliche Arbeit tun

2026-08-24

JSON ist das toleranteste Datenformat der Welt — und genau das ist seine Schwäche. Eine API akzeptiert {"user_id": 123}, und irgendein Aufrufer sendet {"user_id": "123"} oder {"userId": 123} oder {}. Niemand beschwert sich, bis später etwas abstürzt. JSON Schema ist der Vertrag, der das verhindert. Es ist ein JSON-Dokument, das ein anderes JSON-Dokument beschreibt: welchen Typ jedes Feld haben muss, welche Felder erforderlich sind, wie Zeichenketten und Zahlen aussehen dürfen und wie Arrays und verschachtelte Objekte geformt sind. Diese Anleitung geht durch die Handvoll Schlüsselwörter, die 90 % der echten Validierung abdecken.

Ein Schema ist ein JSON-Dokument

Ein Schema ist gewöhnliches JSON mit einer besonderen $schema-Markierung und einem type:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "age": { "type": "integer" }
  },
  "required": ["name"]
}

Lesen Sie es als eine Menge von Constraints, nicht als Rezept: „Der Wert muss ein Objekt sein; sein name muss eine Zeichenkette sein und ist erforderlich; sein age muss, falls vorhanden, eine Ganzzahl sein.“ Jede Daten, die die Constraints erfüllt, validiert; zusätzliche Daten sind erlaubt, sofern Sie sie nicht verbieten (siehe additionalProperties unten).

Das Typsystem

Das Schlüsselwort type akzeptiert: object, array, string, number, integer, boolean, null. Ein Wert, der nicht zum deklarierten Typ passt, fällt sofort durch die Validierung.

{ "type": "string" }      // "hello" ✓  |  42 ✗
{ "type": ["string", "null"] }  // beides ist erlaubt

Die Array-Form ["string", "null"] ist das idiomatische „nullable“ — ein Feld, das null oder eine Zeichenkette ist. (Draft 2020-12 fügte type: "null" hinzu und verschob type-Arrays, doch die Array-Form funktioniert noch überall.)

Objekte: properties, required, additionalProperties

Drei Schlüsselwörter definieren die Objektvalidierung:

  • properties — eine Zuordnung Feldname → Schema. Der Wert jedes deklarierten Felds wird gegen sein Schema validiert.
  • required — ein Array von Feldnamen, die vorhanden sein müssen. Fehlen ist standardmäßig nicht ungültig; nur aufgeführte Felder sind Pflicht.
  • additionalProperties — was mit Feldern geschieht, die nicht in properties stehen. Standard: erlaubt. false verbietet sie (strikte Verträge); ein Schema validiert sie locker.
{
  "type": "object",
  "properties": {
    "id": { "type": "integer" },
    "tags": { "type": "array" }
  },
  "required": ["id"],
  "additionalProperties": false
}

additionalProperties: false ist der Strenge-Schalter, der Tippfehler wie user_id vs. userId an der Grenze abfängt statt stromabwärts.

Zeichenketten und Zahlen

Zeichenketten bekommen Längen- und Muster-Constraints; Zahlen bekommen Bereich und Vielfaches:

{
  "type": "string",
  "minLength": 3,
  "maxLength": 50,
  "pattern": "^[a-z0-9-]+$"
}
{
  "type": "number",
  "minimum": 0,
  "exclusiveMinimum": 0,
  "maximum": 100,
  "multipleOf": 0.5
}

exclusiveMinimum / exclusiveMaximum (in draft-04 boolesch, ab draft-06 ein eigenes Schlüsselwort) drücken strikte Ungleichungen aus. pattern ist ein vollständiger Regex-Match, keine „enthält“-Suche.

Arrays

Arrays validieren jedes Element, dazu Größe und Eindeutigkeit:

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

items als einzelnes Schema validiert jedes Element auf dieselbe Weise. Als Array (prefixItems in 2020-12) ist es ein Tupel: Element 0 gegen Schema 0, Element 1 gegen Schema 1 und so weiter — die richtige Form für fixe Positionen wie Koordinatenpaare.

Komposition: oneOf, allOf, anyOf und $ref

Echte Verträge brauchen Verzweigungslogik:

  • oneOf — genau ein Subschema muss passen: „entweder eine E-Mail-Adresse oder eine Telefonnummer“.
  • anyOf — mindestens eines muss passen (nützlich für „Zeichenkette oder Array von Zeichenketten“).
  • allOf — alle müssen passen (Basis-Constraints mit Extras kombinieren).
  • $ref — verweist auf ein Schema anderswo im selben Dokument ("$ref": "#/$defs/address") oder in einem anderen Dokument. So verwenden Sie eine Form wieder, statt sie zu wiederholen:
{
  "type": "object",
  "properties": {
    "billing": { "$ref": "#/$defs/address" },
    "shipping": { "$ref": "#/$defs/address" }
  },
  "$defs": {
    "address": {
      "type": "object",
      "required": ["street", "city"],
      "additionalProperties": false
    }
  }
}

Eine Warnung: $ref ist in draft-07 exklusiv (es ersetzt benachbarte Schlüsselwörter), legen Sie gemeinsame Logik also in $defs und referenzieren Sie sie, statt $ref mit properties am selben Knoten zu mischen.

Wofür Schemas wirklich gut sind

Validierung ist nur der Anfang. Ein gutes Schema ist eine Quelle der Wahrheit, die antreibt:

  • API-Request-/Response-Validierung — schlechte Payloads an der Grenze mit präzisen Fehlermeldungen zurückweisen.
  • Generierte Formulare — ein schema-getriebener Formularrenderer baut Felder, Typen und Pflichtfelder direkt aus dem Vertrag, sodass Formular und API nicht auseinanderdriften können.
  • Testdatengenerierung — das Schema einem Generator geben und realistische, gültige Fixtures für jeden Zweig des Vertrags erhalten.
  • Dokumentation — das Schema ist die API-Spezifikation für die Form Ihrer Daten.

Dasselbe Dokument dient allen vier Zwecken, weshalb ein strenges Schema sich über die Validierung hinaus auszahlt.

Kurzreferenz

  • Ein Schema ist ein JSON-Dokument aus Constraints; $schema deklariert den Dialekt, type die äußere Form.
  • Typen: object, array, string, number, integer, boolean, null; ["string","null"] für nullable.
  • Objekte: properties (Schemas pro Feld), required (Pflichtliste), additionalProperties: false (Strenge).
  • Zeichenketten: minLength, maxLength, pattern (vollständiger Match). Zahlen: minimum, exclusiveMinimum, maximum, multipleOf.
  • Arrays: items (pro Element) oder Tupel per Array-Form; minItems, maxItems, uniqueItems.
  • Verzweigung: oneOf (genau eines), anyOf (mindestens eines), allOf (alle) und $ref, um eine Form aus $defs wiederzuverwenden.
  • In draft-07 ersetzt $ref benachbarte Schlüsselwörter am selben Knoten — referenzieren Sie in $defs, statt zu mischen.
  • Ein Schema treibt Validierung, generierte Formulare, Testdaten und Doku aus einer Quelle der Wahrheit.

Um statt per Hand ein Schema für Ihr JSON zu bauen, leitet der JSON-Schema-Generator die Form aus einer Stichprobe ab oder baut sie visuell, macht der Testdatengenerator daraus realistische Fixtures, und der JSON-Formatierer hält Ihre Quelldaten lesbar, während Sie den Vertrag entwerfen. Schemas stehen neben den anderen JSON-Kopfschmerzen aus häufige JSON-Fehler und der Konfigurationsfalle in YAML — bei allen dreien geht es darum, nachsichtigen Text in verlässliche Daten zu verwandeln.

Verwandte Tools