Validierung mit JSON Schema und Zod
Auf dieser Seite
Lektion aktualisiert am 3. November 2026 basierend auf der OpenAI-Dokumentation:
temperatureundtop_pwerden nur mit einem Reasoning-Effort vonnoneakzeptiert, während GPT-5.6-Modelle standardmäßig mitmediumreasonieren. Aufrufe, die diese Parameter setzen, müssen daherreasoning={"effort": "none"}(Responses API) oderreasoning_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