Ověřování pomocí JSON Schema a Zod
Na této stránce
Lekce aktualizována 3. listopadu 2026 na základě dokumentace OpenAI: parametry
temperatureatop_pjsou přijímány pouze při úsilí o uvažování (reasoning effort) nastaveném nanone, zatímco modely GPT-5.6 ve výchozím nastavení uvažují (medium). Volání, která tyto parametry nastavují, musí proto specifikovatreasoning={"effort": "none"}(Responses API) neboreasoning_effort="none"(Chat Completions). Zdroje: Používání GPT-6 · GPT-5.6 Terra.
Ověřování pomocí JSON Schema a Zod
Strukturovaný výstup (Structured Output) zaručuje strukturu odpovědi, nikoliv však sémantickou platnost dat. Pole „email“ může obsahovat řetězec, který není platnou e-mailovou adresou. Ověřování na straně klienta pomocí JSON Schema nebo Zod je nezbytným doplňkem pro robustní pipeline.
Proč ověřovat až po přijetí
Udělej si přehled o tom, co API zaručuje, a rozdělení práce bude jasné. Strukturovaný výstup OpenAI zajišťuje, že JSON je syntakticky platný, že jsou dodrženy deklarované typy (řetězec zůstává řetězcem, celé číslo celým číslem), že jsou přítomna všechna povinná pole a že hodnoty omezené výčtem (enum) patří do seznamu. Na tyto čtyři body se můžeš při psaní kódu spolehnout.
Vše ostatní je na tobě a pokrývá čtyři rodiny problémů. Omezení formátu unikají přísnému schématu: nic nebrání modelu vrátit jean.dupont(at)example.fr v poli email nebo datum ve formátu 15/03/2026, když očekáváš ISO. Meze nejsou kontrolovány ani pro délku řetězce, ani pro rozsah čísel: věk 350 projde bez mrknutí oka. Konzistence mezi poli zůstává nedosažitelná – end_date dřívější než start_date je dokonale platný JSON. A obchodní platnost nemá důvod API zajímat: SIRET (francouzské IČO) musí mít čtrnáct číslic, ale to je znalost tvé domény, nikoliv dekodéru.
Tyto čtyři rodiny sdílejí děsivou vlastnost: nezpůsobují viditelné chyby. Špatně formátovaný e-mail uložený do databáze se neprojeví, dokud za několik týdnů neodskočí e-mailová kampaň. Proto platí pravidlo: ověřuj před persistencí, nikdy až po ní.
Ověřování v Pythonu pomocí jsonschema
Praktickým důsledkem je, že potřebuješ dvě schémata pro stejná data. První jde do API, je úmyslně strohé a omezené na to, co přijímá striktní režim. Druhé zůstává u tebe a nese jemná omezení – format, pattern, minimum, maximum. Tato zdánlivá duplikace je oddělením odpovědností: jedno rámec generování, druhé brání tvé úložiště. V níže uvedeném příkladu se v obou objevuje pouze výčet rolí (enum), protože je to jediné omezení, které mohou vyjádřit obě úrovně.
import json
from jsonschema import validate, ValidationError
# Schéma pro OpenAI API (striktní, bez 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
}
# Rozšířené schéma pro ověřování na straně klienta
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]:
"""Ověří odpověď LLM proti rozšířenému schématu."""
try:
validate(instance=data, schema=validation_schema)
return True, "Valid"
except ValidationError as e:
return False, f"Error: {e.message}"
Ověřování pomocí Pydantic
Pydantic je pro ověřování v Pythonu často pohodlnější než jsonschema a rozdíl spočívá v tom, co dostaneš na výstupu. jsonschema ti řekne ano či ne a nechá tě s slovníkem, se kterým manipuluješ přes data["email"] bez pomoci editoru. Pydantic vrací typizovaný objekt: funguje automatické doplňování, překlep v názvu atributu je zachycen již při psaní a data poté cirkulují bez konverze.
Model ContactExtraction vyjadřuje meze přímo v deklaracích polí. field_validator na date_extraction pokrývá případ, který žádná typová anotace nezachytí: řetězec je skutečně řetězec, ale musí představovat reálné datum – 2026-02-31 vyhoví jakémukoli rozumnému pattern, přesto neexistuje. Funkce pro extrakci ukazuje celý řetězec, od strohého schématu poslaného do API až po ověřenou instanciaci.
from pydantic import BaseModel, Field, field_validator
from pydantic import EmailStr
from datetime import date
class ContactExtraction(BaseModel):
"""Ověřovací schéma pro extrakci kontaktů."""
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:
"""Extrahuje kontakt a ověří data."""
# Schéma pro API (bez jemných omezení)
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)
# Ověření Pydantic s jemnými omezeními
return ContactExtraction(**data)
Ověřování pomocí Zod (TypeScript/Node.js)
Pokud je tvůj backend v TypeScriptu, je Zod referenčním nástrojem a přináší výhodu, kterou Pydantic nemusí poskytovat: z.infer odvozuje typ TypeScriptu přímo z ověřovacího schématu. Tvar popíšeš jednou a kompilátor poté zná strukturu Invoice, aniž bys musel udržovat paralelní rozhraní, takže nehrozí riziko divergence.
Níže uvedené schéma faktury ilustruje rozdělení práce: na straně API je siret jen řetězec; na straně Zod musí mít přesně čtrnáct znaků a obsahovat pouze číslice. Konečné parse vyhodí výjimku, pokud data neodpovídají, a to je žádoucí chování – hlasitá chyba, která přeruší zpracování dokumentu, je lepší než faktura s fiktivním SIRET uložená v databázi mezi deseti tisíci ostatními.
import { z } from "zod";
import OpenAI from "openai";
const client = new OpenAI();
// Zod schéma s jemnými validacemi
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);
// Ověření Zod s jemnými omezeními
return InvoiceSchema.parse(data);
}
Vzorec: opakování s opravou
Když ověření selže, pošli chybu zpět modelu k opravě. Tento reflex mění povahu selhání: datum ve špatném formátu již není výjimkou bublající až k uživateli, ale extra round-tripem několika set milisekund, kterého si nikdo nevšimne. Mechanismus je jednoduchý – znovu vložíme ověřovací zprávu do promptu pro další pokus, takže model přesně ví, co se pokazilo, místo aby podruhé hádal naslepo.
Toto pohodlí však vyžaduje hranice. Omez počet pokusů, jinak tě nemožné omezení – například pattern příliš přísný pro zahraniční čísla – bude stát volání v nekonečné smyčce. A sleduj míru opakování: pokud čtvrtina tvých extrakcí projde přes retry, problém leží v počátečním promptu nebo schématu, nikoliv v modelu.
def extract_with_retry(prompt: str, schema: dict,
validator, max_retries: int = 3) -> dict:
"""Extrahuje a ověřuje s automatickým opakováním."""
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 requires 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}")
Testovací prostředí pro pozvánky do kalendáře
Vytvoř schéma Pydantic pro extrakci událostí – název, datum, čas, místo, účastníci – a zapoj ho za volání Strukturovaného výstupu. Otestuj to na pěti e-mailech obsahujících pozvánky, přičemž se ujisti, že zahrneš alespoň jeden, kde je čas napsán slovy („čtvrtek dopoledne“), a jeden, kde je místo implicitní („jako obvykle v zasedačce“). To jsou případy, které lámou ověření, a v reálné poště dominují.
Poté přidej automatické opakování a změř dvě čísla: míru úspěšnosti na první pokus a míru po opakování. Druhé číslo ti řekne, co ti oprava přináší, první zda bys měl přepracovat své instrukce, než se spoléhat na druhou šanci.
Klíčové poznatky
- Strukturovaný výstup zaručuje strukturu, nikoliv sémantickou platnost
- Používej dvě schémata: jedno pro API (striktní), jedno pro ověření na klientovi
- Pydantic (Python) a Zod (TypeScript) jsou referenční nástroje
- Vzorec opakování se zpětnou vazbou opraví většinu chyb ověření
- Vždy ověřuj na straně klienta před uložením dat