Zum Hauptinhalt springen
Deutsch— Sprache auswählen
Menü

Validierung mit JSON Schema und Zod

Lektion 11 von 16 Aktualisiert am 3. November 2026 Entwickler
Auf dieser Seite
  1. Validierung mit JSON Schema und Zod
  2. Warum Validierung nach Erhalt
  3. Python-Validierung mit jsonschema
  4. Validierung mit Pydantic
  5. Validierung mit Zod (TypeScript/Node.js)
  6. Muster: Wiederholen mit Korrektur
  7. Eine Testbank für Kalender-Einladungen
  8. Kernaussagen

Lektion aktualisiert am 3. November 2026 basierend auf der OpenAI-Dokumentation: temperature und top_p werden nur mit einem Reasoning-Effort von none akzeptiert, während GPT-5.6-Modelle standardmäßig mit medium reasonieren. Aufrufe, die diese Parameter setzen, müssen daher reasoning={"effort": "none"} (Responses API) oder reasoning_effort="none" (Chat Completions) angeben. Quellen: Verwendung von GPT-6 · GPT-5.6 Terra.

Validierung mit JSON Schema und Zod

Strukturierte Ausgabe garantiert die Antwortstruktur, nicht jedoch die semantische Gültigkeit der Daten. Ein Feld „email” kann beispielsweise einen String enthalten, der keine gültige E-Mail-Adresse ist. Die clientseitige Validierung mittels JSON Schema oder Zod ist die wesentliche Ergänzung für eine robuste Pipeline.

Warum Validierung nach Erhalt

Machen Sie sich klar, welche Garantien die API bietet, und die Arbeitsteilung ergibt sich von selbst. Die Strukturierte Ausgabe von OpenAI stellt sicher, dass das JSON syntaktisch gültig ist, dass deklarierte Typen eingehalten werden – ein String bleibt ein String, eine Ganzzahl bleibt eine Ganzzahl –, dass alle erforderlichen Felder vorhanden sind und dass Werte, die durch ein enum eingeschränkt sind, der Liste angehören. Bei diesen vier Punkten können Sie Ihren Code mit Zuversicht schreiben.

Alles andere liegt in Ihrer Verantwortung und umfasst vier Problemfamilien. Formatbeschränkungen entkommen dem strengen Schema: Das Modell kann beispielsweise jean.dupont(at)example.fr in einem email-Feld zurückgeben oder ein Datum im Format 15/03/2026, wenn ISO erwartet wird. Grenzen werden ebenfalls nicht geprüft, weder für die String-Länge noch für den Zahlenbereich: ein Alter von 350 wird ohne Wimpernblinzeln akzeptiert. Die konsistenz zwischen Feldern bleibt unerreichbar – ein end_date, das vor start_date liegt, ist völlig gültiges JSON. Und geschäftliche Gültigkeit hat keinen Grund, die API zu interessieren: Eine SIRET (französische Unternehmens-ID) muss aus vierzehn Ziffern bestehen, aber das ist Ihr Domänenwissen, nicht das Wissen des Decoders.

Diese vier Problemfamilien teilen eine erschreckende Eigenschaft: Sie verursachen keine sichtbaren Fehler. Eine fehlerhafte E-Mail, die in die Datenbank gespeichert wird, manifestiert sich erst, wenn die E-Mail-Kampagne Wochen später zurückgewiesen wird. Daher die Regel: Validieren Sie vor der Persistierung, niemals danach.

Python-Validierung mit jsonschema

Die praktische Konsequenz ist, dass Sie für dieselben Daten zwei Schemas benötigen. Das erste geht an die API, absichtlich schlank und auf das beschränkt, was Strict Mode akzeptiert. Das zweite bleibt bei Ihnen und trägt die feingranularen Einschränkungen – format, pattern, minimum, maximum. Diese scheinbare Duplizierung ist eine Trennung der Belange: Das eine rahmt die Generierung ein, das andere verteidigt Ihre Speicherung. Im folgenden Beispiel erscheint nur das enum für die Rolle in beiden, da dies die einzige Einschränkung ist, die beide Ebenen ausdrücken können.

import json
from jsonschema import validate, ValidationError

# Schema für die OpenAI API (streng, ohne format/pattern)
api_schema = {
    "type": "object",
    "properties": {
        "email": {"type": "string"},
        "age": {"type": "integer"},
        "role": {"type": "string", "enum": ["admin", "user", "viewer"]}
    },
    "required": ["email", "age", "role"],
    "additionalProperties": False
}

# Erweitertes Schema für die clientseitige Validierung
validation_schema = {
    "type": "object",
    "properties": {
        "email": {
            "type": "string",
            "format": "email",
            "pattern": r"^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\.[a-zA-Z]{2,}$"
        },
        "age": {
            "type": "integer",
            "minimum": 0,
            "maximum": 150
        },
        "role": {"type": "string", "enum": ["admin", "user", "viewer"]}
    },
    "required": ["email", "age", "role"]
}

def validate_response(data: dict) -> tuple[bool, str]:
    """Validiert die LLM-Antwort gegen das erweiterte Schema."""
    try:
        validate(instance=data, schema=validation_schema)
        return True, "Valid"
    except ValidationError as e:
        return False, f"Error: {e.message}"

Validierung mit Pydantic

Pydantic ist für die Validierung in Python oft bequemer als jsonschema, und der Unterschied liegt in dem, was Sie als Ausgabe erhalten. jsonschema sagt Ihnen nur Ja oder Nein und hinterlässt Ihnen ein Wörterbuch, das Sie über data["email"] manipulieren müssen, ohne editorische Unterstützung. Pydantic gibt Ihnen ein typisiertes Objekt zurück: Autocomplete funktioniert, Tippfehler im Attributnamen werden zum Schreibzeitpunkt erkannt, und die Daten zirkulieren danach ohne Konvertierung.

Das Modell ContactExpression drückt Grenzen direkt in den Felddeklarationen aus. Der field_validator für date_extraction deckt den Fall ab, den keine Typannotation erfassen kann: der String ist zwar tatsächlich ein String, muss aber ein echtes Datum repräsentieren – 2026-02-31 erfüllt jedes vernünftige pattern, existiert aber nicht. Die Extraktionsfunktion zeigt die gesamte Kette, vom schlanken Schema, das an die API gesendet wird, bis zur validierten Instanziierung.

from pydantic import BaseModel, Field, field_validator
from pydantic import EmailStr
from datetime import date

class ContactExtraction(BaseModel):
    """Validierungsschema für die Kontaktextraktion."""
    last_name: str = Field(min_length=2, max_length=100)
    first_name: str = Field(min_length=2, max_length=100)
    email: EmailStr
    phone: str = Field(pattern=r"^\+?[0-9\s\-\.]{10,15}$")
    company: str
    title: str
    extraction_date: str

    @field_validator("extraction_date")
    @classmethod
    def validate_date(cls, v):
        try:
            date.fromisoformat(v)
            return v
        except ValueError:
            raise ValueError(f"Invalid date: {v}")

def extract_and_validate(text: str) -> ContactExtraction:
    """Extrahiert einen Kontakt und validiert die Daten."""
    # Schema für die API (ohne feingranulare Einschränkungen)
    api_schema = {
        "type": "object",
        "properties": {
            "last_name": {"type": "string"},
            "first_name": {"type": "string"},
            "email": {"type": "string"},
            "phone": {"type": "string"},
            "company": {"type": "string"},
            "title": {"type": "string"},
            "extraction_date": {"type": "string"}
        },
        "required": ["last_name", "first_name", "email", "phone",
                      "company", "title", "extraction_date"],
        "additionalProperties": False
    }

    response = client.responses.create(
        model="gpt-5.6-terra",
        instructions="Extract contact information. "
                     "Date format: YYYY-MM-DD.",
        input=text,
        text={
            "format": {
                "type": "json_schema",
                "name": "contact",
                "schema": api_schema,
                "strict": True
            }
        }
    )

    data = json.loads(response.output_text)
    # Pydantic-Validierung mit feingranularen Einschränkungen
    return ContactExtraction(**data)

Validierung mit Zod (TypeScript/Node.js)

Wenn Ihr Backend in TypeScript geschrieben ist, ist Zod das Referenzwerkzeug, und es bringt einen Vorteil mit, den Pydantic nicht bieten muss: z.infer leitet den TypeScript-Typ direkt aus dem Validierungsschema ab. Sie beschreiben die Form einmal, und der Compiler kennt dann die Struktur von Invoice, ohne dass Sie eine parallele Schnittstelle warten müssen, sodass kein Risiko einer Divergenz besteht.

Das untenstehende Rechnungsschema illustriert die Arbeitsteilung: Auf der API-Seite ist siret einfach ein String; auf der Zod-Seite muss er genau vierzehn Zeichen lang sein und nur Ziffern enthalten. Der finale parse wirft eine Ausnahme, wenn die Daten nicht passen, und das ist das gewünschte Verhalten – ein lauter Fehler, der die Dokumentverarbeitung unterbricht, ist besser als eine fantasievolle SIRET-Rechnung, die in der Datenbank unter zehntausend anderen gespeichert ist.

import { z } from "zod";
import OpenAI from "openai";

const client = new OpenAI();

// Zod-Schema mit feingranularen Validierungen
const InvoiceSchema = z.object({
  number: z.string().regex(/^[A-Z]{2}-\d{4}-\d{4}$/),
  date: z.string().date(),
  amount_excl_tax: z.number().positive(),
  vat_rate: z.number().min(0).max(100),
  amount_incl_tax: z.number().positive(),
  supplier: z.object({
    name: z.string().min(2),
    siret: z.string().length(14).regex(/^\d+$/),
  }),
});

type Invoice = z.infer<typeof InvoiceSchema>;

async function extractInvoice(text: string): Promise<Invoice> {
  const response = await client.responses.create({
    model: "gpt-5.6-terra",
    instructions: "Extract invoice data.",
    input: text,
    text: {
      format: {
        type: "json_schema",
        name: "invoice",
        schema: {
          type: "object",
          properties: {
            number: { type: "string" },
            date: { type: "string" },
            amount_excl_tax: { type: "number" },
            vat_rate: { type: "number" },
            amount_incl_tax: { type: "number" },
            supplier: {
              type: "object",
              properties: {
                name: { type: "string" },
                siret: { type: "string" },
              },
              required: ["name", "siret"],
              additionalProperties: false,
            },
          },
          required: ["number", "date", "amount_excl_tax",
                     "vat_rate", "amount_incl_tax", "supplier"],
          additionalProperties: false,
        },
        strict: true,
      },
    },
  });

  const data = JSON.parse(response.output_text);

  // Zod-Validierung mit feingranularen Einschränkungen
  return InvoiceSchema.parse(data);
}

Muster: Wiederholen mit Korrektur

Wenn die Validierung fehlschlägt, senden Sie den Fehler zurück an das Modell zur Korrektur. Dieser Reflex ändert die Natur des Fehlers: ein Datum im falschen Format ist keine Ausnahme, die zum Benutzer aufblubert, sondern eine zusätzliche Hin- und Herfahrt von wenigen hundert Millisekunden, die niemand bemerkt. Der Mechanismus ist einfach – wir injizieren die Validierungsnachricht in den Prompt des nächsten Versuchs, sodass das Modell genau weiß, was schiefgelaufen ist, statt blind ein zweites Mal zu raten.

Dieser Komfort erfordert jedoch Grenzen. Begrenzen Sie die Anzahl der Versuche, oder eine unmögliche Einschränkung – ein pattern, das für ausländische Nummern zu streng ist, zum Beispiel – wird Ihnen Aufrufe in einer Schleife kosten. Und überwachen Sie die Wiederholungsrate: Wenn ein Viertel Ihrer Extraktionen eine Wiederholung benötigt, liegt das Problem in der ursprünglichen Anweisung oder dem Schema, nicht im Modell.

def extract_with_retry(prompt: str, schema: dict,
                       validator, max_retries: int = 3) -> dict:
    """Extrahiert und validiert mit automatischer Wiederholung."""
    last_error = None

    for attempt in range(max_retries):
        input_text = prompt
        if last_error:
            input_text += (f"\n\nWARNING: Your previous response had "
                          f"this validation error: {last_error}\n"
                          f"Correct and try again.")

        response = client.responses.create(
            model="gpt-5.6-terra",
            reasoning={"effort": "none"},  # temperature erfordert effort none
            input=input_text,
            text={"format": {"type": "json_schema",
                             "name": "data",
                             "schema": schema,
                             "strict": True}},
            temperature=0.1
        )

        data = json.loads(response.output_text)
        is_valid, error = validator(data)

        if is_valid:
            return data
        last_error = error

    raise ValueError(f"Failed after {max_retries} attempts: {last_error}")

Eine Testbank für Kalender-Einladungen

Erstellen Sie ein Pydantic-Schema, um Ereignisse zu extrahieren – Titel, Datum, Uhrzeit, Ort, Teilnehmer – und stecken Sie es hinter einen Aufruf für Strukturierte Ausgabe. Testen Sie es mit fünf E-Mails, die Einladungen enthalten, und stellen Sie sicher, dass mindestens eine enthalten ist, in der die Uhrzeit ausgeschrieben ist (“später am Donnerstagmorgen”), und eine, in der der Ort implizit ist (“wie immer im Sitzungszimmer”). Dies sind die Fälle, die die Validierung brechen, und sie dominieren in einem echten Posteingang.

Fügen Sie dann die automatische Wiederholung hinzu und messen Sie zwei Kennzahlen: die Erfolgsquote beim ersten Versuch und die Quote nach der Wiederholung. Die zweite sagt Ihnen, was die Korrektur für Sie bringt, die erste, ob Sie Ihre Anweisungen überarbeiten sollten, statt auf eine zweite Chance zu zählen.

Kernaussagen

  • Strukturierte Ausgabe garantiert Struktur, nicht semantische Gültigkeit
  • Verwenden Sie zwei Schemas: eines für die API (streng), eines für die clientseitige Validierung
  • Pydantic (Python) und Zod (TypeScript) sind die Referenzwerkzeuge
  • Das Muster „Wiederholen mit Feedback” korrigiert die meisten Validierungsfehler
  • Validieren Sie clientseitig immer vor der Persistierung der Daten