Validácia pomocou JSON Schema a Zod
Na tejto strane
Lekcia aktualizovaná 3. novembra 2026 na základe dokumentácie OpenAI: parametre
temperatureatop_psú akceptované len pri úsilí o logické uvažovanie (reasoning effort) nastavenom nanone, zatiaľ čo modely GPT-5.6 predvolene logicky uvažujú (medium). Volania, ktoré nastavujú tieto parametre, preto musia špecifikovaťreasoning={"effort": "none"}(Responses API) aleboreasoning_effort="none"(Chat Completions). Zdroje: Používanie GPT-6 · GPT-5.6 Terra.
Validácia pomocou JSON Schema a Zod
Štruktúrovaný výstup (Structured Output) zaručuje štruktúru odpovede, nie však sémantickú platnosť údajov. Pole „email“ môže obsahovať reťazec, ktorý nie je platnou e-mailovou adresou. Validácia na strane klienta pomocou JSON Schema alebo Zod je nevyhnutným doplnkom pre robustné pipeline.
Prečo validovať po prijatí
Urob si inventár toho, čo API zaručuje, a rozdelenie práce bude jasné. Štruktúrovaný výstup OpenAI zabezpečuje, že JSON je syntakticky platný, že deklarované typy sú dodržané – reťazec zostáva reťazcom, celé číslo zostáva celým číslom – že všetky požadované polia sú prítomné a že hodnoty obmedzené pomocou enum patria do zoznamu. V týchto štyroch bodoch môžeš písať svoj kód s istotou.
Všetko ostatné je na tebe a pokrýva to štyri rodiny problémov. Obmedzenia formátu unikajú prísnej schéme: nič nebráni modelu vrátiť jean.dupont(at)example.fr v poli email alebo dátum vo formáte 15/03/2026, keď očakávaš ISO. Hranice sa tiež nekontrolujú, ani pre dĺžku reťazca, ani pre rozsah čísla: vek 350 prejde bez žmurknutia. Konzistencia medzi poľami zostáva nedosiahnuteľná – end_date skôr ako start_date je dokonale platný JSON. A obchodná platnosť nemá dôvod zaujímať API: SIRET (francúzske identifikačné číslo podniku) musí mať štrnásť číslic, ale to je znalosť tvojej domény, nie dekodéra.
Tieto štyri rodiny majú jednu desivú črtu: nespôsobujú viditeľné chyby. Chybne formátovaný e-mail uložený do databázy sa neprejaví, kým o týždne neodskočí e-mailová kampaň. Preto pravidlo znie: validuj pred persistenciou, nikdy nie po nej.
Validácia v Pythone pomocou jsonschema
Praktickým dôsledkom je, že potrebuješ dve schémy pre tie isté údaje. Prvá ide do API, úmyselne strohá, obmedzená na to, čo akceptuje prísny režim. Druhá zostáva u teba a nesie jemné obmedzenia – format, pattern, minimum, maximum. Táto zdanlivá duplikácia je separáciou zodpovedností: jedna rámec generovania, druhá bráni tvoje úložisko. V nižšie uvedenom príklade sa v oboch objavuje iba enum pre rolu, pretože je to jediné obmedzenie, ktoré môžu vyjadriť obe úrovne.
import json
from jsonschema import validate, ValidationError
# Schéma pre OpenAI API (prísna, 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šírená schéma pre validáciu na strane 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]:
"""Validuje odpoveď LLM proti rozšírenej schéme."""
try:
validate(instance=data, schema=validation_schema)
return True, "Valid"
except ValidationError as e:
return False, f"Error: {e.message}"
Validácia pomocou Pydantic
Pydantic je často pohodlnejší ako jsonschema pre validáciu v Pythone a rozdiel spočíva v tom, čo dostaneš na výstupe. jsonschema ti povie áno alebo nie a nechá ťa so slovníkom, s ktorým manipuluješ cez data["email"] bez pomoci editora. Pydantic vracia typizovaný objekt: automatické dopĺňanie funguje, preklep v názve atribútu je zachytený už pri písaní a údaje následne cirkulujú bez konverzie.
Model ContactExtraction vyjadruje hranice priamo v deklaráciách polí. field_validator na date_extraction pokrýva prípad, ktorý žiadna typová anotácia nezachytí: reťazec je síce reťazec, ale musí predstavovať skutočný dátum – 2026-02-31 spĺňa akúkoľvek rozumnú pattern, no neexistuje. Funkcia extrakcie ukazuje celý reťazec, od strohej schémy odoslanej do API až po validovanú inštanciu.
from pydantic import BaseModel, Field, field_validator
from pydantic import EmailStr
from datetime import date
class ContactExtraction(BaseModel):
"""Validačná schéma pre extrakciu kontaktov."""
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 validuje údaje."""
# Schéma pre API (bez jemných obmedzení)
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="Extrahuj kontaktné informácie. "
"Formát dátumu: YYYY-MM-DD.",
input=text,
text={
"format": {
"type": "json_schema",
"name": "contact",
"schema": api_schema,
"strict": True
}
}
)
data = json.loads(response.output_text)
# Validácia Pydantic s jemnými obmedzeniami
return ContactExtraction(**data)
Validácia pomocou Zod (TypeScript/Node.js)
Ak je tvoj backend v TypeScripte, Zod je referenčný nástroj a prináša výhodu, ktorú Pydantic nemusí poskytovať: z.infer odvodzuje TypeScript typ priamo z validačnej schémy. Tvar popíšeš raz a kompilátor následne pozná štruktúru Invoice bez toho, aby si musel udržiavať paralelné rozhranie, takže nehrozí riziko divergencie.
Nižšie uvedená schéma faktúry ilustruje rozdelenie práce: na strane API je siret len reťazec; na strane Zod musí mať presne štrnásť znakov a obsahovať iba číslice. Záverečné parse vyhodí výnimku, ak údaje nezapadajú, a to je želané správanie – hlasná chyba, ktorá preruší spracovanie dokumentu, je lepšia ako faktúra s fiktívnym SIRET uložená v databáze medzi desiatkami tisíc ďalších.
import { z } from "zod";
import OpenAI from "openai";
const client = new OpenAI();
// Zod schéma s jemnými validáciami
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: "Extrahuj údaje z faktúry.",
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);
// Validácia Zod s jemnými obmedzeniami
return InvoiceSchema.parse(data);
}
Vzorec: opakovanie s opravou
Keď validácia zlyhá, pošli chybu späť modelu na opravu. Tento reflex mení povahu zlyhania: dátum v nesprávnom formáte už nie je výnimkou, ktorá bublá až k používateľovi, ale extra cestou tam a späť trvajúcou niekoľko stoviek milisekúnd, ktorú si nikto nevšimne. Mechanizmus je jednoduchý – znovu vstrekujeme validačnú správu do promptu pre ďalší pokus, takže model presne vie, čo sa pokazilo, namiesto toho, aby druhýkrát hádal naslepo.
Tento komfort si však vyžaduje hranice. Obmedz počet pokusov, inak ťa nemožné obmedzenie – napríklad pattern príliš prísny pre zahraničné čísla – bude stáť volania v slučke. A sleduj mieru opakovaní: ak štvrtina tvojich extrakcií prejde cez retry, problém leží v počiatočnom prompte alebo schéme, nie v modeli.
def extract_with_retry(prompt: str, schema: dict,
validator, max_retries: int = 3) -> dict:
"""Extrahuje a validuje s automatickým opakovaní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}")
Testovacie prostredie pre pozvánky do kalendára
Vytvor schému Pydantic na extrakciu udalostí – názov, dátum, čas, miesto, účastníci – a zapoj ju za volanie Štruktúrovaného výstupu. Otestuj to na piatich e-mailoch obsahujúcich pozvánky, pričom sa uisti, že zahrnieš aspoň jeden, kde je čas napísaný slovne („štvrtok neskoro dopoludnia“) a jeden, kde je miesto implicitné („ako zvyčajne v zasadačke“). Toto sú prípady, ktoré lámu validáciu, a v reálnej schránke dominujú.
Potom pridaj automatické opakovanie a zmeraj dve čísla: mieru úspešnosti na prvý pokus a mieru po opakovaní. Druhé číslo ti povie, čo ti opraví, prvé či by si mal prepracovať svoje inštrukcie, namiesto toho, aby si sa spoliehal na druhú šancu.
Kľúčové poznatky
- Štruktúrovaný výstup zaručuje štruktúru, nie sémantickú platnosť
- Používaj dve schémy: jednu pre API (prísnu), jednu pre validáciu na strane klienta
- Pydantic (Python) a Zod (TypeScript) sú referenčné nástroje
- Vzorec opakovania so spätnou väzbou opraví väčšinu chýb validácie
- Vždy validuj na strane klienta pred persistenciou údajov