Validacija s JSON Schema i Zod
Na ovoj stranici
Lekcija ažurirana 3. studenog 2026. na temelju OpenAI dokumentacije:
temperatureitop_pprihvaćeni su samo uz napor razmišljanja (reasoning effort) odnone, dok GPT-5.6 modeli prema zadanim postavkama razmišljaju (medium). Pozivi koji postavljaju ove parametre stoga moraju specificiratireasoning={"effort": "none"}(Responses API) ilireasoning_effort="none"(Chat Completions). Izvori: Korištenje GPT-6 · GPT-5.6 Terra.
Validacija s JSON Schema i Zod
Strukturirani izlaz (Structured Output) jamči strukturu odgovora, ali ne i semantičku valjanost podataka. Polje „email“ može sadržavati niz koji nije valjana adresa e-pošte. Validacija na strani klijenta pomoću JSON Schema ili Zod bitan je dodatak za robustan pipeline.
Zašto validirati nakon primitka
Uzmimo u obzir što API jamči i podjela rada postat će jasna. OpenAI-jev Strukturirani izlaz osigurava da je JSON sintaktički ispravan, da su deklarirani tipovi poštovani – niz ostaje niz, cijeli broj ostaje cijeli broj – da su sva obavezna polja prisutna i da vrijednosti ograničene s enum pripadaju popisu. Na ove četiri točke možeš pisati svoj kod s povjerenjem.
Sve ostalo je na tebi, pokrivajući četiri obitelji problema. Ograničenja formata izmiču strogoj shemi: ništa ne sprječava model da vrati jean.dupont(at)example.fr u polju email ili datum u formatu 15/03/2026 kada očekuješ ISO. Granice se također ne provjeravaju, ni za duljinu niza ni za raspon brojeva: dob od 350 godina proći će bez treptaja. Dosljednost između polja ostaje nedostižna – end_date raniji od start_date savršeno je valjan JSON. A poslovna valjanost nema razloga brinuti API: SIRET (francuski identifikacijski broj tvrtke) mora imati četrnaest znamenki, ali to je znanje tvoje domene, a ne dekodera.
Ove četiri obitelji dijele zastrašujuću osobinu: ne uzrokuju vidljive pogreške. Neispravan email spremljen u bazu podataka neće se manifestirati sve dok kampanja e-pošte ne bude odbijena tjednima kasnije. Otuda pravilo: validiraj prije trajnog spremanja, nikada poslije.
Python validacija s jsonschema
Praktična posljedica je da ti trebaju dvije sheme za iste podatke. Prva ide API-ju, namjerno mršava, ograničena na ono što strogi način prihvaća. Druga ostaje kod tebe i nosi fino podešena ograničenja – format, pattern, minimum, maximum. Ova prividna dupliciranost zapravo je odvajanje odgovornosti: jedna okviruje generiranje, druga brani tvoju pohranu. U primjeru ispod, samo enum uloge pojavljuje se u obje, jer je to jedino ograničenje koje obje razine mogu izraziti.
import json
from jsonschema import validate, ValidationError
# Shema za OpenAI API (stroga, 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
}
# Proširena shema za validaciju na strani klijenta
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]:
"""Validira LLM odgovor protiv proširene sheme."""
try:
validate(instance=data, schema=validation_schema)
return True, "Valid"
except ValidationError as e:
return False, f"Error: {e.message}"
Validacija s Pydanticom
Pydantic je često prikladniji od jsonschema za validaciju u Pythonu, a razlika leži u onome što dobiješ na izlazu. jsonschema ti kaže da ili ne i ostavlja te s rječnikom, kojim manipuliraš putem data["email"] bez pomoći uređivača. Pydantic vraća tipizirani objekt: automatsko dovršavanje radi, tipfeler u nazivu atributa uhvaćen je u vrijeme pisanja, a podaci nakon toga kruže bez konverzije.
Model ContactExtraction izražava granice izravno u deklaracijama polja. field_validator na date_extraction pokriva slučaj koji nijedna anotacija tipa ne može uhvatiti: niz je doista niz, ali mora predstavljati stvaran datum – 2026-02-31 zadovoljava svaki razuman pattern, ali ne postoji. Funkcija ekstrakcije prikazuje cijeli lanac, od mršave sheme poslane API-ju do validirane instancijacije.
from pydantic import BaseModel, Field, field_validator
from pydantic import EmailStr
from datetime import date
class ContactExtraction(BaseModel):
"""Shema validacije za ekstrakciju kontakata."""
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:
"""Ekstrahira kontakt i validira podatke."""
# Shema za API (bez fino podešenih ograničenja)
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 validacija s fino podešenim ograničenjima
return ContactExtraction(**data)
Validacija sa Zod (TypeScript/Node.js)
Ako je tvoj backend u TypeScriptu, Zod je referentni alat, i donosi prednost koju Pydantic ne mora pružati: z.infer izvodi TypeScript tip izravno iz sheme validacije. Opisuješ oblik jednom, a kompajler tada zna strukturu Invoice bez da održavaš paralelno sučelje, pa nema rizika od razilaženja.
Shema fakture u nastavku ilustrira podjelu rada: na strani API-ja, siret je samo niz; na strani Zoda, mora imati točno četrnaest znakova i sadržavati samo znamenke. Konačni parse podiže iznimku ako podaci ne odgovaraju, a to je željeno ponašanje – glasna pogreška koja prekida obradu dokumenta bolja je od fantomske fakture sa SIRET-om pohranjene u bazi podataka među deset tisuća drugih.
import { z } from "zod";
import OpenAI from "openai";
const client = new OpenAI();
// Zod shema s fino podešenim validacijama
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 validacija s fino podešenim ograničenjima
return InvoiceSchema.parse(data);
}
Obrazac: ponovni pokušaj s ispravkom
Kada validacija ne uspije, pošalji pogrešku natrag modelu na ispravak. Ovaj refleks mijenja prirodu neuspjeha: datum u pogrešnom formatu više nije iznimka koja iskače korisniku, već dodatno putovanje od nekoliko stotina milisekundi koje nitko ne primijeti. Mehanizam je jednostavan – ponovno ubacujemo poruku o validaciji u prompt sljedećeg pokušaja, tako da model točno zna što je pošlo po zlu umjesto da nagađa nasumično drugi put.
Ova udobnost zahtijeva granice, međutim. Ograniči broj pokušaja, inače će te nemoguće ograničenje – primjerice pattern prestrogi za strane brojeve – koštati poziva u petlji. I prati stopu ponovnih pokušaja: ako četvrtina tvojih ekstrakcija prolazi kroz ponovni pokušaj, problem leži u početnom promptu ili shemi, a ne u modelu.
def extract_with_retry(prompt: str, schema: dict,
validator, max_retries: int = 3) -> dict:
"""Ekstrahira i validira s automatskim ponovnim pokušajem."""
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}")
Testna klupa za pozivnice kalendara
Izgradi Pydantic shemu za ekstrakciju događaja – naslov, datum, vrijeme, lokacija, sudionici – zatim je uključi iza poziva Strukturiranog izlaza. Testiraj na pet emailova koji sadrže pozivnice, pazeći da uključiš barem jedan gdje je vrijeme napisano riječima („četvrtak kasno ujutro“) i jedan gdje je lokacija implicitna („kao i obično u vijećnici“). To su slučajevi koji ruše validaciju, a dominiraju u stvarnoj pristigloj pošti.
Zatim dodaj automatski ponovni pokušaj i izmjeri dvije brojke: stopu uspjeha iz prvog pokušaja i stopu nakon ponovnog pokušaja. Druga ti govori što ispravak donosi, prva trebaš li preraditi svoje upute umjesto da računaš na drugu priliku.
Ključne točke
- Strukturirani izlaz jamči strukturu, a ne semantičku valjanost
- Koristi dvije sheme: jednu za API (strogu), jednu za validaciju klijenta
- Pydantic (Python) i Zod (TypeScript) su referentni alati
- Obrazac ponovnog pokušaja s povratnom informacijom ispravlja većinu pogrešaka validacije
- Uvijek validiraj na strani klijenta prije trajnog spremanja podataka