Output JSON strutturato da un modello: schema, validazione e retry limitato (Python, pydantic)
Il JSON di un modello può comunque essere sbagliato. Valida con pydantic in modalità strict, rimanda gli errori poche volte, poi fermati. Codice testato, senza chiavi API.

Chiedere un JSON a un modello è facile. Fidarsi della risposta è la parte difficile. Il testo può essere tagliato a metà per il limite di token, avvolto in un blocco Markdown, contenere un campo che non hai chiesto, usare una categoria che non è nella tua lista, oppure scrivere "3" dove il tuo codice si aspetta il numero 3. Se il programma passa quel risultato direttamente a un database o a un altro servizio, l'errore compare lontano da dove è nato.
In questa guida costruiamo la parte tra il modello e il resto del codice: uno schema pydantic rigoroso, un passaggio di validazione che dice esattamente cosa non va e un ciclo di retry che rimanda gli errori al modello per un numero limitato di volte. L'esempio non richiede chiavi API: i test usano un modello finto con risposte predefinite, quindi verificano il nostro codice e nient'altro. Non dicono quanto spesso un modello reale sbaglia: misuralo con il tuo provider e i tuoi prompt.
Versioni verificate il 2026-11-17: pydantic 2.14.3 su PyPI (pubblicato il 2026-11-05), che richiede Python 3.10 o successivo; i test sono girati su Python 3.11 e nella CI su 3.12. Si tratta solo Python; la stessa idea funziona in qualsiasi linguaggio con una libreria di validazione.
Tre livelli di "strutturato"
"Output strutturato" indica tre cose diverse, e confonderle crea sorprese:
| Livello | Cosa fai | Cosa garantisce |
|---|---|---|
| Chiedere nel prompt | "Rispondi con un JSON fatto così: ..." | Niente. Di solito il modello obbedisce, a volte no. |
| Vincolare la generazione | Passi uno JSON Schema a una funzione del provider che limita i token producibili | Il testo segue lo schema, nei limiti di ciò che quella funzione supporta. Quali parole chiave accetta e come fallisce va letto nella documentazione del provider: qui non ho provato nessun provider. |
| Validare nel tuo codice | Analizzi e controlli il testo con una libreria che governi tu | Il programma non riceve mai dati che violano le tue regole. |
Il terzo livello è l'unico che non dipende dal provider, e serve anche quando usi il secondo: una risposta vincolata può comunque essere tagliata dal limite massimo di output, può essere un rifiuto e può rispettare lo schema pur essendo sbagliata nel significato. Lo schema controlla la forma, non la verità. Quindi valida sempre, e fai derivare dallo stesso codice lo schema che mandi al provider.
Un modello, due usi
L'esempio classifica un messaggio di assistenza. Il modello pydantic è sia il contratto per il tuo codice sia la fonte dello JSON Schema:
import json
import re
from typing import Callable, Literal
from pydantic import BaseModel, ConfigDict, Field, ValidationError
class Ticket(BaseModel):
"""What we want the model to return for each support message."""
# extra="forbid": a field we did not ask for is an error, not silently dropped.
# strict=True: "3" is not accepted for an int, true/false only for a bool.
model_config = ConfigDict(extra="forbid", strict=True)
category: Literal["billing", "bug", "feature", "other"]
priority: int = Field(ge=1, le=5)
summary: str = Field(min_length=1, max_length=120)
needs_human: bool
Due impostazioni fanno la maggior parte del lavoro:
extra="forbid"trasforma un campo inatteso in un errore. Il valore predefinito è'ignore': i dati in più vengono scartati in silenzio, quindi un campo facoltativo scritto male non verrebbe mai notato.strict=Trueferma la conversione dei tipi. Per impostazione predefinita pydantic converte quando può: la pagina sulla strict mode mostra'123'che diventa l'intero123. È comodo per i campi di un modulo; per l'output di un modello nasconde gli errori. Il test qui sotto mostra la differenza su un input equivalente.
Literal[...] dà un elenco chiuso di valori e Field(ge=1, le=5) un intervallo numerico. Ticket.model_json_schema() restituisce lo JSON Schema del modello (pagina JSON Schema). Un test controlla cosa produce: la categoria diventa un enum, la priorità riceve minimum 1 e maximum 5, e extra="forbid" diventa additionalProperties: false.
Valida il testo, non un dizionario
La chiamata centrale è model_validate_json, che analizza e valida in un solo passaggio (pagina JSON). Un JSON non valido non è un'eccezione a parte: torna anch'esso come ValidationError, con tipo di errore json_invalid. Un solo except copre entrambi i casi.
try:
return model.model_validate_json(strip_fence(raw)), attempt
except ValidationError as e: # also covers invalid JSON (type "json_invalid")
last_error = e
messages.append({"role": "assistant", "content": raw})
messages.append({"role": "user", "content": feedback(e)})
strip_fence rimuove un blocco di codice Markdown se il modello lo ha aggiunto. Non fa altro, volutamente. Cercare la prima { nel testo e tagliare l'ultima } è il modo per accettare mezza risposta incollata a mezza di un'altra. Un testo che non è esattamente JSON è un errore, e se ne occupa il ciclo di retry; il test test_text_around_json_is_not_repaired fissa questa scelta.
_FENCE = re.compile(r"^```(?:json)?\s*(.*?)\s*```$", re.DOTALL)
def strip_fence(text: str) -> str:
"""Models often wrap JSON in a Markdown code fence. Remove exactly one fence, nothing else."""
m = _FENCE.match(text.strip())
return m.group(1) if m else text.strip()
def feedback(error: ValidationError) -> str:
"""Tell the model what was wrong: field path, error type, message. Never the input values."""
lines = []
for e in error.errors(include_input=False, include_url=False):
where = ".".join(str(p) for p in e["loc"]) or "(root)"
lines.append(f"- {where}: {e['msg']} [{e['type']}]")
return "The JSON was not valid. Fix these problems and answer with the corrected JSON only:\n" + "\n".join(lines)
Guarda cosa lascia fuori feedback. Invia il percorso del campo, il messaggio e il tipo di errore, ma non il valore prodotto dal modello. errors() accetta include_input=False e include_url=False (vedi il riferimento a ValidationError.errors in pydantic-core). Un valore non valido può essere lungo e può contenere dati personali copiati dal messaggio dell'utente. Il modello ha già la propria risposta precedente nella conversazione, come mostra il ciclo qui sotto.
Il ciclo di retry limitato
def extract(call_model: Callable[[list], str], prompt: str, model=Ticket, max_attempts: int = 3):
"""Ask the model, validate the answer, and on failure send the errors back.
call_model(messages) -> str is your own wrapper around any provider.
Returns (validated_object, attempts_used).
"""
messages = [{"role": "user", "content": prompt}]
last_error = None
for attempt in range(1, max_attempts + 1):
raw = call_model(messages)
try:
return model.model_validate_json(strip_fence(raw)), attempt
except ValidationError as e: # also covers invalid JSON (type "json_invalid")
last_error = e
messages.append({"role": "assistant", "content": raw})
messages.append({"role": "user", "content": feedback(e)})
raise StructuredOutputError(max_attempts, last_error)
Come funziona, passo per passo:
- Il primo messaggio è il tuo prompt.
call_modelè una funzione che scrivi tu: riceve la lista dei messaggi e restituisce il testo. Ci avvolgi dentro l'SDK del tuo provider; l'esempio non chiama nessun provider. - Se la validazione riesce, restituisce l'oggetto e il numero di tentativi usati. Registra quel numero: è la metrica di qualità più economica che hai.
- Se fallisce, la risposta del modello viene aggiunta come messaggio
assistant, seguita da un messaggiousercon l'elenco degli errori. Il modello vede cosa ha scritto e cosa non va. - Dopo
max_attemptssollevaStructuredOutputError. Nessun ciclo infinito, e il costo di una richiesta ha un tetto.
Il valore predefinito è 3 tentativi. Un modello a cui si dice category: Input should be 'billing', 'bug', 'feature' or 'other' riceve un'istruzione precisa da correggere. Non ho misurato quanto spesso funzioni con un modello reale, quindi è una scelta di progetto, non un risultato. Misura il tuo tasso di errori prima di consentire più tentativi: ogni tentativo in più è una nuova chiamata a pagamento (vedi l'articolo su token e costi).
Cosa dimostrano i test
Quindici test, tutti offline. Il più utile mostra perché la strict mode conta. Un input equivalente viene accettato da un modello predefinito (lax) e rifiutato da quello strict:
def test_lax_mode_quietly_coerces_strings(self):
t = LaxTicket.model_validate_json('{"category": "bug", "priority": "3", "needs_human": "yes"}')
self.assertEqual((t.priority, t.needs_human), (3, True)) # "3" -> 3 and "yes" -> True
def test_strict_mode_rejects_the_same_input(self):
with self.assertRaises(ValidationError) as cm:
extract.Ticket.model_validate_json(
'{"category": "bug", "priority": "3", "summary": "x", "needs_human": "yes"}')
types = {e["type"] for e in cm.exception.errors()}
self.assertEqual(types, {"int_type", "bool_type"})
Altri test coprono un campo in più (extra_forbidden), un valore fuori da enum e intervallo (literal_error e less_than_equal in un solo passaggio, così il modello riceve tutti i problemi insieme) e una risposta tagliata a 40 caratteri, come se si fosse fermata per max_tokens (json_invalid).
Il test del retry controlla la conversazione stessa, non solo il risultato:
def test_errors_are_sent_back_and_second_answer_is_accepted(self):
bad = '{"category": "urgent", "priority": 2, "summary": "Login fails", "needs_human": true}'
model = FakeModel(bad, GOOD)
t, attempts = extract.extract(model, "classify: login fails")
self.assertEqual(attempts, 2)
second_call = model.calls[1]
self.assertEqual([m["role"] for m in second_call], ["user", "assistant", "user"])
self.assertEqual(second_call[1]["content"], bad) # its own bad answer is shown back
self.assertIn("category: Input should be", second_call[2]["content"])
self.assertIn("[literal_error]", second_call[2]["content"])
Un ultimo test verifica che il feedback non rimandi indietro l'input non valido: una "category" che contiene un numero di carta viene rifiutata e il secondo prompt contiene solo il testo degli errori.
Trappole trovate
- Chiavi duplicate. Se un oggetto JSON ripete una chiave, pydantic usa l'ultimo valore, come
json.loads. È documentato e il testtest_duplicate_keys_last_one_winslo conferma. La RFC 8259 dice che i nomi in un oggetto dovrebbero essere unici e che il comportamento del software che riceve duplicati è imprevedibile: non farci affidamento. - Un float non è un int in strict mode.
3.0viene rifiutato per un campointconint_type. Se il tuo provider restituisce numeri come3.0, allenta quel campo o correggi il prompt. - JSON non è Python. La pagina di pydantic nota che JSON non ha un tipo
date, quindi le stringhe di data restano accettate in strict mode quando analizzi JSON. Prova i tipi che usi davvero. - Valido non vuol dire vero. Una risposta come
"priority": 1, "needs_human": falseper un messaggio che dice che l'intero servizio è fermo rispetta tutte le regole sopra. La validazione non può accorgersene. Per il significato serve una valutazione (un campione di risposte controllato da persone o da un secondo passaggio), che è un argomento a sé. - Non usare l'analisi parziale per il risultato.
pydantic_core.from_jsonpuò analizzare un JSON incompleto conallow_partial=True, utile per mostrare una risposta in streaming mentre cresce. Una risposta finale troncata resta un errore: lì vogliamojson_invalid, e il comportamento predefinito lo dà. - Testo dell'utente nel prompt. Il testo che classifichi può contenere istruzioni. La validazione limita la forma dell'output, non ciò che il modello viene convinto a scrivere dentro campi validi; vedi prompt injection: difese pratiche.
Quando il retry non è la risposta
Un retry corregge una svista di formato, non un prompt ambiguo o uno schema troppo difficile. Se molte chiamate hanno bisogno di un secondo tentativo, cambia il prompt o lo schema prima di alzare max_attempts: descrivi ogni campo con Field(description=...), mostra un esempio, semplifica gli oggetti annidati, oppure rendi facoltativo un campo quando l'informazione spesso manca.
Tieni inoltre separati due tipi di guasto. Un errore di validazione è un problema di contenuto, quindi la risposta è un'altra chiamata al modello con il feedback. Un errore di rete, un 429 o un timeout è un problema di trasporto e ha regole proprie: vedi l'articolo su 429 e Retry-After e quello su timeout e cancellazione. Tieni i due cicli distinti e fai coprire a un unico budget di tempo entrambi. Per vedere cosa fa una certa politica di retry sul numero di chiamate c'è il simulatore di retry e backoff, e il riferimento dei codici di stato HTTP elenca quali stati vale la pena riprovare.
Quando viene sollevato StructuredOutputError, dai al chiamante un esito chiaro: mettere l'elemento in coda per una persona, restituire un errore o usare un valore predefinito scelto in anticipo. Registra percorsi dei campi e tipi di errore, non il testo dell'utente, per vedere quale campo fallisce più spesso.
Provalo tu
Il codice è nella cartella structured-output del repository di esempi (licenza MIT):
pip install -r requirements.txt # pydantic==2.14.3
python -m unittest -v
La CI di questo articolo è verde. Qui nulla chiama un modello reale, quindi quanto spesso il primo tentativo è valido e quanto costa il retry resta da misurare a te.
In sintesi
- Valida sempre nel tuo codice, anche se il provider può vincolare l'output a uno schema.
- Scrivi il contratto una volta in pydantic:
Literalper elenchi chiusi,Fieldper gli intervalli,extra="forbid"estrict=Trueperché gli errori restino errori e non diventino conversioni silenziose. - Usa
model_validate_json: JSON non valido e valori sbagliati escono come la stessaValidationError, con un percorso di campo e un tipo di errore per ogni problema. - Rimanda quegli errori, senza i valori di input, per un numero limitato di tentativi, e tieni questo ciclo separato da quello dei retry di rete.
- Una risposta valida non è una risposta corretta: prevedi un controllo separato sul significato.
Fonti: pydantic JSON, pydantic strict mode, pydantic JSON Schema, pydantic error handling, pydantic models, RFC 8259, The JSON Data Interchange Format, JSON Schema.
L'esempio completo e testato di questo articolo è nel nostro repository pubblico: adamant-solutions/ai-dev-examples/structured-output