title: JSON Schema
description: Tutorial about JSON Schema - what it is, how to define, test, and use it
tags: 
  - schema
  - validation
  - api
  - data-format
  - javascript
  - json
pageType: concept
created: 2026-04-13

JSON Schema

JSON Schema ist eine deklarative Sprache, die Sie verwenden können, um JSON-Dokumente zu annotieren und zu validieren. Sie können sich JSON Schema wie einen Vertrag für Ihre JSON-Daten vorstellen - er definiert, wie die Daten aussehen sollten, welche Typen sie haben sollen, gültige Werte und Beziehungen zwischen Feldern.

Was wird JSON Schema verwendet für?

Wie wird es definiert?

Ein JSON Schema ist selbst ein JSON-Dokument. Die grundlegende Struktur folgt diesem Muster:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "User Profile",
  "description": "Ein Benutzerprofil mit optionalen Details",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "age": {
      "type": "integer",
      "minimum": 0,
      "maximum": 150
    },
    "email": {
      "type": "string",
      "format": "email"
    },
    "is_active": {
      "type": "boolean",
      "default": true
    },
    "roles": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "minItems": 1
    }
  },
  "required": ["name", "email"],
  "additionalProperties": false
}

Wichtige Komponenten

Komponente Beschreibung Beispiel
$schema Version des Schema-Specs, die verwendet werden soll "https://json-schema.org/draft/2020-12/schema"
title Menschlich lesbarer Titel "Benutzerprofil"
description Menschlich beschreibende Beschreibung "Ein Benutzer mit grundlegenden Infos"
type Primitive Datentypen "string", "object", "array"
properties Definitionen von Feldern "name": { "type": "string" }
required Felder, die vorhanden sein müssen ["name", "email"]
additionalProperties Ob zusätzliche Felder erlaubt sind false (streng)

Häufige Typen

Häufige Schlüsselwörter

{
  "type": "string",
  "enum": ["admin", "user", "guest"],  // Muss einer dieser Werte sein
  "pattern": "^\\d+$",                  // Regex-Muster
  "format": "email",                    // E-Mail, uri, date-time, uuid, etc.
  "minLength": 1,
  "maxLength": 50,
  "default": "guest"
}

Wie wird JSON Schema verwendet?

1. JavaScript/Node.js

const Ajv = require("ajv");
const ajv = new Ajv(); // options: { allErrors: true }

const schema = {
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "age": { "type": "integer" }
  },
  "required": ["name"]
};

const validate = ajv.compile(schema);

const data = { name: "Alice", age: 30 };
const valid = validate(data);

if (valid) {
  console.log("Daten sind gültig!");
} else {
  console.log("Validierungsfehler:", validate.errors);
}

2. Python

from jsonschema import validate, ValidationError

schema = {
    "type": "object",
    "properties": {
        "name": {"type": "string"},
        "age": {"type": "integer"}
    },
    "required": ["name"]
}

data = {"name": "Alice", "age": 30}

try:
    validate(instance=data, schema=schema)
    print("Daten sind gültig!")
except ValidationError as e:
    print(f"Validierungsfehler: {e.message}")

3. Go

package main

import (
    "encoding/json"
    "fmt"
    "github.com/xeipuuv/gojsonschema"
)

func main() {
    schemaLoader := gojsonschema.NewReferenceLoader("file:///path/to/schema.json")
    documentLoader := gojsonschema.NewStringLoader(`{"name": "Alice", "age": 30}`)

    result, err := gojsonschema.Validate(schemaLoader, documentLoader)
    if err != nil {
        panic(err)
    }

    if result.Valid() {
        fmt.Println("Das Dokument ist gültig")
    } else {
        fmt.Println("Das Dokument ist nicht gültig. siehe fehler:")
        for _, desc := range result.Errors() {
            fmt.Println("-", desc)
        }
    }
}

Wie wird JSON Schema getestet?

1. Online-Validatoren

2. CLI-Tools

# Using ajv-cli (Node.js)
npm install -g ajv-cli
ajv validate -s schema.json -d data.json

# Using Python's jsonschema CLI
pip install jsonschema
jsonschema --instance data.json --schema schema.json

3. Testing mit Testdaten

# Testdaten generieren
npm install -g json-schema-faker
json-schema-faker -s schema.json -r > test-data.json

4. Automatisierte Tests

const ajv = require("ajv");

const ajv = new Ajv({ allErrors: true });
const validate = ajv.compile(schema);

describe("Benutzervalidierung", () => {
  test("gültiger Benutzer sollte bestehen", () => {
    const validData = { name: "Alice", email: "alice@example.com" };
    expect(validate(validData)).toBe(true);
  });

  test("Benutzer ohne E-Mail sollte fehlschlagen", () => {
    const invalidData = { name: "Bob" };
    expect(validate(invalidData)).toBe(false);
    expect(validate.errors).toHaveLength(1);
  });
});

Best Practices

  1. Verwenden Sie $schema-Schlüsselwort um die Version zu spezifizieren (aktuell: 2020-12 oder draft-07)
  2. Bewahren Sie Schemas klein und wiederverwendbar - Nutzen Sie $ref für gängige Muster
  3. Dokumentieren Sie mit title und description für API-Nutzer
  4. Setzen Sie additionalProperties: false auf Objekten, die Sie streng validieren wollen
  5. Nutzen Sie oneOf, anyOf, allOf für komplexe Validierungsregeln
  6. Versionieren Sie Ihre Schemas (z.B. user-v1.json, user-v2.json)
  7. Schreiben Sie Tests für Schema-Ränder - leere Objekte, null-Werte, zusätzliche Eigenschaften

Beispiel für ein komplexes Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://example.com/schemas/product.json",
  "title": "Product",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "pattern": "^PROD-\\d+$"
    },
    "name": {
      "type": "string",
      "minLength": 3
    },
    "price": {
      "type": "number",
      "minimum": 0,
      "multipleOf": 0.01
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "uniqueItems": true
    },
    "metadata": {
      "type": "object",
      "properties": {
        "created_at": { "format": "date-time" },
        "updated_at": { "format": "date-time" }
      }
    }
  },
  "required": ["id", "name", "price"],
  "additionalProperties": false
}