Validazione con JSON Schema e Zod
In questa pagina
Lezione aggiornata il 3 novembre 2026 sulla base della documentazione OpenAI:
temperatureetop_psono accettati solo con uno sforzo di ragionamento pari anone, mentre i modelli GPT-5.6 ragionano per impostazione predefinita (medium). Le chiamate che impostano questi parametri devono quindi specificarereasoning={"effort": "none"}(API Responses) oreasoning_effort="none"(Chat Completions). Fonti: Using GPT-6 · GPT-5.6 Terra.
Validazione con JSON Schema e Zod
L’Output Strutturato garantisce la struttura della risposta, ma non la validità semantica dei dati. Un campo “email” potrebbe contenere una stringa che non è un indirizzo email valido. La validazione lato client tramite JSON Schema o Zod è il complemento essenziale per una pipeline robusta.
Perché validare dopo la ricezione
Fai il punto su ciò che l’API garantisce e la divisione del lavoro diventa chiara. L’Output Strutturato di OpenAI assicura che il JSON sia sintatticamente valido, che i tipi dichiarati siano rispettati (una stringa rimane una stringa, un intero rimane un intero), che tutti i campi obbligatori siano presenti e che i valori vincolati da un enum appartengano all’elenco. Su questi quattro punti, puoi scrivere il tuo codice con fiducia.
Tutto il resto spetta a te, coprendo quattro famiglie di problemi. I vincoli di formato sfuggono allo schema rigoroso: nulla impedisce al modello di restituire jean.dupont(at)example.fr in un campo email, o una data nel formato 15/03/2026 quando ti aspetti ISO. Nemmeno i limiti vengono controllati, né per la lunghezza della stringa né per l’intervallo numerico: un’età di 350 passerà senza battere ciglio. La coerenza tra campi rimane fuori portata: una end_date precedente alla start_date è un JSON perfettamente valido. E la validità aziendale non ha motivo di preoccupare l’API: un SIRET (identificativo aziendale francese) deve essere di quattordici cifre, ma questa è conoscenza del tuo dominio, non del decodificatore.
Queste quattro famiglie condividono un tratto inquietante: non causano errori visibili. Un’email malformata salvata nel database non si manifesterà fino a quando la campagna email non rimbalzerà settimane dopo. Da qui la regola: valida prima di persistere, mai dopo.
Validazione Python con jsonschema
La conseguenza pratica è che hai bisogno di due schemi per gli stessi dati. Il primo va all’API, intenzionalmente snello, limitato a ciò che la modalità strict accetta. Il secondo rimane con te e porta i vincoli granulari: format, pattern, minimum, maximum. Questa apparente duplicazione è una separazione delle responsabilità: uno incornicia la generazione, l’altro difende il tuo storage. Nell’esempio seguente, solo l’enum del ruolo appare in entrambi, perché è l’unico vincolo che entrambi i livelli possono esprimere.
import json
from jsonschema import validate, ValidationError
# Schema per OpenAI API (strict, senza 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
}
# Schema esteso per la validazione lato client
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]:
"""Valida la risposta LLM rispetto allo schema esteso."""
try:
validate(instance=data, schema=validation_schema)
return True, "Valid"
except ValidationError as e:
return False, f"Error: {e.message}"
Validazione con Pydantic
Pydantic è spesso più comodo di jsonschema per la validazione in Python, e la differenza sta in ciò che ottieni in output. jsonschema ti dice sì o no e ti lascia con un dizionario, manipolato tramite data["email"] senza assistenza dell’editor. Pydantic restituisce un oggetto tipizzato: l’autocompletamento funziona, un errore di battitura nel nome di un attributo viene rilevato al momento della scrittura e i dati circolano successivamente senza conversione.
Il modello ContactExtraction esprime i limiti direttamente nelle dichiarazioni dei campi. Il field_validator su date_extraction copre il caso che nessuna annotazione di tipo può catturare: la stringa è effettivamente una stringa, ma deve rappresentare una data reale: 2026-02-31 soddisfa qualsiasi pattern ragionevole eppure non esiste. La funzione di estrazione mostra l’intera catena, dallo schema snello inviato all’API all’istanziazione validata.
from pydantic import BaseModel, Field, field_validator
from pydantic import EmailStr
from datetime import date
class ContactExtraction(BaseModel):
"""Schema di validazione per l'estrazione dei contatti."""
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:
"""Estrae un contatto e valida i dati."""
# Schema per API (senza vincoli granulari)
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)
# Validazione Pydantic con vincoli granulari
return ContactExtraction(**data)
Validazione con Zod (TypeScript/Node.js)
Se il tuo backend è in TypeScript, Zod è lo strumento di riferimento e porta un vantaggio che Pydantic non ha bisogno di fornire: z.infer deriva il tipo TypeScript direttamente dallo schema di validazione. Descrivi la forma una volta sola e il compilatore conosce quindi la struttura di Invoice senza che tu debba mantenere un’interfaccia parallela, quindi non c’è rischio di divergenza.
Lo schema della fattura seguente illustra la divisione del lavoro: lato API, siret è solo una stringa; lato Zod, deve essere esattamente di quattordici caratteri e contenere solo cifre. Il parse finale solleva un’eccezione se i dati non corrispondono, ed è il comportamento desiderato: un errore rumoroso che interrompe l’elaborazione del documento è meglio di una fattura con SIRET fantasioso archiviata nel database tra altre diecimila.
import { z } from "zod";
import OpenAI from "openai";
const client = new OpenAI();
// Schema Zod con validazioni granulari
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);
// Validazione Zod con vincoli granulari
return InvoiceSchema.parse(data);
}
Pattern: retry con correzione
Quando la validazione fallisce, invia l’errore al modello per la correzione. Questo riflesso cambia la natura del fallimento: una data nel formato sbagliato non è più un’eccezione che risale fino all’utente, ma un round trip extra di poche centinaia di millisecondi che nessuno nota. Il meccanismo è semplice: reiniettiamo il messaggio di validazione nel prompt del tentativo successivo, così il modello sa esattamente cosa è andato storto invece di indovinare alla cieca una seconda volta.
Questo comfort richiede però dei limiti. Metti un cappuccio al numero di tentativi, altrimenti un vincolo impossibile (un pattern troppo rigido per numeri stranieri, ad esempio) ti costerà chiamate in loop. E monitora il tasso di retry: se un quarto delle tue estrazioni passa attraverso un retry, il problema risiede nel prompt iniziale o nello schema, non nel modello.
def extract_with_retry(prompt: str, schema: dict,
validator, max_retries: int = 3) -> dict:
"""Estrae e valida con retry automatico."""
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 richiede 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}")
Un banco di prova per gli inviti al calendario
Costruisci uno schema Pydantic per estrarre eventi (titolo, data, ora, luogo, partecipanti), quindi collegalo dietro una chiamata di Output Strutturato. Testa su cinque email contenenti inviti, assicurandoti di includerne almeno una in cui l’ora è scritta per esteso (“giovedì tarda mattinata”) e una in cui il luogo è implicito (“come al solito nella sala riunioni”). Questi sono i casi che rompono la validazione e dominano in una casella di posta reale.
Aggiungi quindi il retry automatico e misura due cifre: il tasso di successo al primo tentativo e il tasso post-retry. Il secondo ti dice cosa ti compra la correzione, il primo se dovresti rielaborare le tue istruzioni piuttosto che contare su una seconda possibilità.
Punti chiave
- L’Output Strutturato garantisce la struttura, non la validità semantica
- Usa due schemi: uno per l’API (strict), uno per la validazione client
- Pydantic (Python) e Zod (TypeScript) sono gli strumenti di riferimento
- Il pattern retry-con-feedback corregge la maggior parte degli errori di validazione
- Valida sempre lato client prima di persistere i dati