Walidacja za pomocą JSON Schema i Zod
Na tej stronie
Lekcja zaktualizowana 3 listopada 2026 r. na podstawie dokumentacji OpenAI: parametry
temperatureitop_psą akceptowane tylko przy wysiłku rozumowania (reasoning effort) ustawionym nanone, podczas gdy modele GPT-5.6 domyślnie rozumują (medium). Wywołania ustawiające te parametry muszą zatem określaćreasoning={"effort": "none"}(Responses API) lubreasoning_effort="none"(Chat Completions). Źródła: Using GPT-6 · GPT-5.6 Terra.
Walidacja za pomocą JSON Schema i Zod
Wyjście strukturyzowane (Structured Output) gwarantuje strukturę odpowiedzi, ale nie semantyczną poprawność danych. Pole „email“ może zawierać ciąg znaków, który nie jest prawidłowym adresem e-mail. Walidacja po stronie klienta przy użyciu JSON Schema lub Zod jest niezbędnym uzupełnieniem tworzącym solidny pipeline.
Dlaczego walidować po otrzymaniu danych
Przeanalizujmy, co gwarantuje API, a podział zadań stanie się jasny. Strukturyzowane wyjście OpenAI zapewnia, że JSON jest syntaktycznie poprawny, że zadeklarowane typy są przestrzegane – ciąg znaków pozostaje ciągiem, liczba całkowita liczbą całkowitą – że wszystkie wymagane pola są obecne, a wartości ograniczone przez enum należą do listy. W tych czterech kwestiach możesz pisać kod z pełnym zaufaniem.
Reszta leży po Twojej stronie i obejmuje cztery rodziny problemów. Ograniczenia formatu wymykają się ścisłej schemie: nic nie powstrzyma modelu przed zwróceniem jean.dupont(at)example.fr w polu email lub daty w formacie 15/03/2026, gdy oczekujesz ISO. Granice również nie są sprawdzane – ani długość ciągu, ani zakres liczby: wiek 350 lat przejdzie bez mrugnięcia okiem. Spójność między polami pozostaje poza zasięgiem – end_date wcześniejsza niż start_date to całkowicie poprawny JSON. Ważność biznesowa również nie dotyczy API: numer SIRET (francuski identyfikator firmy) musi mieć czternaście cyfr, ale to wiedza Twojej domeny, a nie dekodera.
Te cztery rodziny łączy jedna przerażająca cecha: nie powodują widocznych błędów. Źle sformatowany e-mail zapisany w bazie danych ujawni się dopiero, gdy kampania mailingowa zostanie odrzucona tygodnie później. Stąd zasada: waliduj przed trwałym zapisem, nigdy po.
Walidacja w Pythonie za pomocą jsonschema
Praktyczną konsekwencją jest potrzeba posiadania dwóch schematów dla tych samych danych. Pierwszy trafia do API – jest celowo odchudzony, ograniczony do tego, co tryb ścisły akceptuje. Drugi pozostaje u Ciebie i niesie drobne ograniczenia – format, pattern, minimum, maximum. Ta pozorna duplikacja to w rzeczywistości rozdzielenie odpowiedzialności: jeden ramuje generowanie, drugi broni Twojego magazynu danych. W poniższym przykładzie tylko wyliczenie enum dla roli pojawia się w obu schematach, ponieważ jest to jedyne ograniczenie, które oba poziomy mogą wyrazić.
import json
from jsonschema import validate, ValidationError
# Schemat dla OpenAI API (ścisły, 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
}
# Rozszerzony schemat do walidacji po stronie 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]:
"""Waliduje odpowiedź LLM względem rozszerzonego schematu."""
try:
validate(instance=data, schema=validation_schema)
return True, "Valid"
except ValidationError as e:
return False, f"Error: {e.message}"
Walidacja za pomocą Pydantic
Pydantic jest często wygodniejszy niż jsonschema do walidacji w Pythonie, a różnica polega na tym, co otrzymujesz na wyjściu. jsonschema mówi tylko „tak“ lub „nie“ i zostawia Cię ze słownikiem, którym manipulujesz przez data["email"] bez pomocy edytora. Pydantic zwraca typowany obiekt: działa autouzupełnianie, literówka w nazwie atrybutu zostanie wykryta już podczas pisania kodu, a dane krążą dalej bez konieczności konwersji.
Model ContactExtraction wyraża granice bezpośrednio w deklaracjach pól. Dekorator field_validator dla date_extraction obsługuje przypadek, którego żadna adnotacja typu nie wychwyci: ciąg jest rzeczywiście ciągiem, ale musi reprezentować rzeczywistą datę – 2026-02-31 spełnia każdy rozsądny pattern, a jednak nie istnieje. Funkcja ekstrakcji pokazuje pełny łańcuch: od odchudzonego schematu wysyłanego do API, aż po zwalidowaną instancję.
from pydantic import BaseModel, Field, field_validator
from pydantic import EmailStr
from datetime import date
class ContactExtraction(BaseModel):
"""Schemat walidacji dla ekstrakcji kontaktów."""
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:
"""Ekstrahuje kontakt i waliduje dane."""
# Schemat dla API (bez drobnych ograniczeń)
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)
# Walidacja Pydantic z drobnymi ograniczeniami
return ContactExtraction(**data)
Walidacja za pomocą Zod (TypeScript/Node.js)
Jeśli Twój backend jest napisany w TypeScript, Zod jest narzędziem referencyjnym i wnosi przewagę, której Pydantic nie musi zapewniać: z.infer wyprowadza typ TypeScript bezpośrednio ze schematu walidacji. Opisujesz kształt raz, a kompilator zna następnie strukturę Invoice bez konieczności utrzymywania równoległego interfejsu, więc nie ma ryzyka rozbieżności.
Poniższy schemat faktury ilustruje podział zadań: po stronie API siret to po prostu ciąg znaków; po stronie Zod musi mieć dokładnie czternaście znaków i zawierać tylko cyfry. Końcowe wywołanie parse zgłosi wyjątek, jeśli dane nie pasują, i taki jest pożądany efekt – głośny błąd przerywający przetwarzanie dokumentu jest lepszy niż faktura z fikcyjnym numerem SIRET zapisana w bazie danych wśród dziesięciu tysięcy innych.
import { z } from "zod";
import OpenAI from "openai";
const client = new OpenAI();
// Schemat Zod z drobnymi walidacjami
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);
// Walidacja Zod z drobnymi ograniczeniami
return InvoiceSchema.parse(data);
}
Wzorzec: ponowienie z korektą
Gdy walidacja nie powiedzie się, odeślij błąd z powrotem do modelu w celu korekty. Ten odruch zmienia naturę awarii: data w złym formacie nie jest już wyjątkiem вспływającym do użytkownika, lecz dodatkową rundą trwającą kilkaset milisekund, której nikt nie zauważy. Mechanizm jest prosty – wstrzykujemy komunikat o błędzie walidacji do promptu następnej próby, dzięki czemu model wie dokładnie, co poszło nie tak, zamiast zgadywać w ciemno po raz drugi.
Ten komfort wymaga jednak granic. Ogranicz liczbę prób, inaczej niemożliwe do spełnienia ograniczenie – np. pattern zbyt ścisły dla numerów zagranicznych – kosztować Cię będzie pętlę wywołań. Monitoruj też wskaźnik ponowień: jeśli ćwierć Twoich ekstrakcji przechodzi przez retry, problem leży w początkowym prompcie lub schemacie, a nie w modelu.
def extract_with_retry(prompt: str, schema: dict,
validator, max_retries: int = 3) -> dict:
"""Ekstrahuje i waliduje z automatycznym ponowieniem."""
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}")
Stanowisko testowe dla zaproszeń kalendarzowych
Zbuduj schemat Pydantic do ekstrakcji wydarzeń – tytuł, data, godzina, lokalizacja, uczestnicy – a następnie podłącz go za wywołaniem Structured Output. Przetestuj go na pięciu e-mailach zawierających zaproszenia, upewniając się, że znajdziesz co najmniej jeden, w którym godzina jest zapisana słownie („czwartek późny poranek“) i jeden, w którym lokalizacja jest domyślna („jak zwykle w sali konferencyjnej“). To przypadki, które łamią walidację, a w prawdziwej skrzynce odbiorczej dominują.
Następnie dodaj automatyczne ponowienie i zmierz dwie wartości: wskaźnik sukcesu za pierwszym razem oraz wskaźnik po ponowieniach. Drugi powie Ci, co zyskujesz dzięki korekcie, pierwszy – czy powinieneś poprawić swoje instrukcje, zamiast liczyć na drugą szansę.
Kluczowe wnioski
- Structured Output gwarantuje strukturę, ale nie semantyczną poprawność
- Używaj dwóch schematów: jednego dla API (ścisły), drugiego do walidacji po stronie klienta
- Pydantic (Python) i Zod (TypeScript) to narzędzia referencyjne
- Wzorzec ponowienia z informacją zwrotną koryguje większość błędów walidacji
- Zawsze waliduj po stronie klienta przed trwałym zapisem danych