LLM e output strutturati che si rompono: come scrivere davvero lo Schema per la modalità strict
In sintesi: Attivare strict su un JSON Schema qualunque finisce quasi sempre con un 400: tutti i campi required, additionalProperties:false su ogni oggetto, $ref e allOf vietati. Questa guida mostra come riscrivere uno schema permissivo in una versione compatibile con strict — unioni nullable, limiti rigidi e checklist sul refusal.

Il punto essenziale: strict: true non è un interruttore "sii più rigoroso" — è un contratto che accetta solo un sottoinsieme di JSON Schema. Tutti i campi required, additionalProperties: false su ogni oggetto, $ref e allOf vietati. Se invii lo schema in modalità strict senza riscriverlo, la risposta è un 400, non un output affidabile.
Nella práctica quotidiana la scena si ripete identica: il team ha uno schema ben progettato, con unioni optional, $defs riutilizzabili e additionalProperties lasciato aperto per compatibilità. Poi qualcuno aggiunge "strict": true alla chiamata dell'API, convinto che il modello ora "rispetterà" lo schema. Il risultato immediato è un errore 400 con un messaggio lungo, o peggio, uno schema accettato che però produce output inattesi. La modalità strict non interpreta lo schema con tolleranza: la riscrive da zero in una grammatica che il motore di generazione può seguire letteralmente, e tutto ciò che non entra in quella grammatica viene rifiutato o ignorato. Capire quali regole valgono davvero, prima di inviare la richiesta, è la differenza tra una pipeline stabile e una settimana di debug.
Modalità strict = il tuo JSON Schema viene compilato in una grammatica che il modello deve seguire parola per parola. Tutto ciò che la grammatica non può esprimere viene rifiutato all'invio o silenziosamente ignorato — e in entrambi i casi il problema appare dopo che l'utente lo ha già visto.
Come funziona davvero il motore di strict mode
I modelli non leggono il tuo JSON Schema come farebbe un validatore tradizionale. Quando strict: true è attivo, lo schema viene trasformato in una grammatica vincolata — un'automa a stati finiti che decide, token per token, quali continuazioni sono legali. Il modello genera solo transizioni ammesse dall'automa; non c'è controllo post-generazione che corregga l'output, la correttezza è strutturale.
Questa architettura spiega tutti i comportamenti che sembrano misteriosi. Se un campo non è incluso in required, l'automa deve decidere quando fermarsi: l'unica soluzione sicura è dare al modello la libertà di emettere null, quindi lo schema effettivo ricevuto dal motore avrà quel campo sempre presente. Se un oggetto ammette proprietà aggiuntive, l'automa non può anticipare quali chiavi appariranno, quindi ogni oggetto deve chiudersi rigidamente. Ogni "vietato" nella documentazione nasce da un limite concreto di questa macchina a stati, non da una scelta stilistica di OpenAI.
La seconda conseguenza è più insidiosa: alcune parole chiave JSON Schema (come pattern, minLength, maximum) sono valide per lo schema ma non applicate dalla grammatica. Lo schema viene accettato, la risposta arriva pulita, ma il vincolo non è mai stato rispettato. È il modo più silenzioso di rompere una pipeline: la validazione successiva fallisce in produzione e nessun log mostra un errore di schema.
Le tre regole non negoziabili
Se hai tempo per sistemare una sola cosa, sistemale queste tre. Risolvono l'enorme maggioranza dei 400.
1. Tutti i campi in required, sempre. In modalità strict ogni chiave dichiarata in properties deve apparire in required — anche le facoltative. Il trucco ufficiale per dire "facoltativo" è una union nullable:
{
"type": "object",
"properties": {
"couponCode": { "type": ["string", "null"] }
},
"required": ["couponCode"],
"additionalProperties": false
}
Così l'automa sa esattamente quando la chiave è legale, e il modello esprime "non c'è coupon" con null invece di omettere la chiave.
2. additionalProperties: false su ogni oggetto. Non solo sull'oggetto radice: ogni oggetto annidato, senza eccezioni. Un solo livello lasciato aperto rende l'intero schema non conforme.
3. $ref e allOf vietati. Niente riferimenti, niente $defs, niente composizione. Lo schema deve essere completamente espanso, un albero unico e autonomo. if/then/else e oneOf alle radice seguono la stessa sorte.
Tabella dei termini vietati e di quelli inefficaci
| Parola chiave | Esito in strict mode | Sostituzione consigliata |
|---|---|---|
$ref, $defs |
Respito con 400 | Espansione completa dello schema |
allOf |
Respito con 400 | Unione delle proprietà a mano |
if/then/else |
Respito con 400 | Enum + gestione lato client |
oneOf alla radice |
Problemi / risposta non conforme | Un solo oggetto radice |
Campo non in required |
Cambiato in sempre richiesto | Union nullable ["string", "null"] |
pattern, minLength |
Schema accettato ma vincolo ignorato | Validazione esplicita dopo la risposta |
maximum, format |
Schema accettato ma vincolo ignorato | Verifica lato applicazione |
La riga più pericolosa è l'ultima coppia: lo schema passa la validazione ma il vincolo non esiste. Se la tua logica si fida di pattern, stai costruendo su sabbia.
I limiti rigidi che nessuno legge
Prima di scrivere lo schema, verifica di restare dentro questi confini — superarli produce errori generici difficili da diagnosticare:
| Limite | Valore massimo |
|---|---|
| Proprietà totali per schema | 5000 |
| Profondità di annidamento | 10 livelli |
| Dimensione stringa schema | 120.000 caratteri |
| Valori enum totali | 1000 |
Gli schemi generati automaticamente da framework o da definizioni OpenAPI spesso superano questi limiti senza che nessuno se ne accorga: 6000 proprietà totali, 12 livelli di annidamento, 1500 valori enum sparsi. Il messaggio d'errore dell'API raramente indica quale soglia è stata superata, quindi conviene controllare da sé prima dell'invio.
Riscrittura automatica: script make_strict
Per schemi grandi, la riscrittura manuale non è praticabile. Questo script Python attraversa l'albero e applica le tre regole in modo ricorsivo:
import json
def make_strict(node):
if isinstance(node, dict):
if node.get("type") == "object":
props = node.get("properties", {})
# ogni proprietà diventa required
node["required"] = list(props.keys())
node["additionalProperties"] = False
# i campi "facoltativi" vanno marcati nullable a monte
# elimina ciò che strict non accetta
for k in ("$ref", "$defs", "allOf", "if", "then", "else"):
node.pop(k, None)
return {k: make_strict(v) for k, v in node.items()}
if isinstance(node, list):
return [make_strict(v) for v in node]
return node
schema = json.load(open("schema.json"))
print(json.dumps(make_strict(schema), indent=2))
Due avvertenze. Prima: lo script non indovina quali campi erano facoltativi — dovrai marcare le union nullable tu stesso, preferibilmente nella fonte dello schema e non nel risultato. Seconda: dopo la trasformazione, esegui sempre una richiesta di prova: l'espansione può far superare i limiti di dimensione o di proprietà che prima rispettavi.
Il percorso equivalente in Anthropic
Anthropic non espone un flag strict, ma raggiunge lo stesso risultato con il meccanismo tool: la definizione dello strumento funge da schema, e il modello è vincolato alla sua forma. L'approccio è praticamente identico:
const tool = {
name: "extract_invoice",
description: "Estrae i dati della fattura dal testo",
input_schema: {
type: "object",
properties: {
invoiceNumber: { type: "string" },
totalAmount: { type: ["number", "null"] },
lineItems: {
type: "array",
items: {
type: "object",
properties: {
description: { type: "string" },
quantity: { type: "number" }
},
required: ["description", "quantity"],
additionalProperties: false
}
}
},
required: ["invoiceNumber", "totalAmount", "lineItems"],
additionalProperties: false
}
};
// il modello risponde con una chiamata tool conforme
const response = await anthropic.messages.create({
model: "claude-sonnet-4-5",
max_tokens: 1024,
tools: [tool],
tool_choice: { type: "tool", name: "extract_invoice" },
messages: [{ role: "user", content: testoFattura }]
});
La regola pratica è la stessa: anche lato Anthropic, ogni oggetto ha bisogno di required completo e additionalProperties: false. La differenza sta nel canale di risposta — tool_use invece del contenuto testuale — e nel fatto che il campo refusal è specifico di OpenAI.
Refusal, troncamento e forma rotta: tre guasti, tre rimedi
Anche con uno schema perfetto, l'output può fallire per tre motivi distinti, e confonderli è il modo più rapido di perdere una giornata:
1. refusal non vuoto. OpenAI, in modalità strict, può restituire un campo refusal con il motivo per cui ha declinato la richiesta. Non è un errore di schema — è il modello che rifiuta semanticamente il compito. Il rimedio è rivedere il prompt o la policy, non lo schema.
2. Troncamento per max_tokens. La generazione si interrompe a metà stringa e il JSON non chiude. In modalità strict la risposta, se arriva, è conforme — ma se il budget di token finisce, arriva tagliata. Aumenta max_tokens o riduci le dimensioni attese dell'output. Per scenari ricorrenti, il riparo automatico del JSON troncato ha pattern pronti all'uso.
3. Forma rotta non conforme. Lo schema era aperto (proprietà aggiuntive permesse, campi non in required) e strict non era attivo: il modello produce JSON valido ma che non rispetta il contratto. Il rimedio è riscrivere lo schema come in questa guida, non aggiungere controlli post-generazione.
La diagnosi corretta parte sempre dal distinguere questi tre casi: guardare il campo finish_reason, la presenza di refusal, e confrontare la risposta con lo schema effettivamente inviato.
Checklist finale prima della messa in produzione
| Punto di controllo | Cosa verificare |
|---|---|
required completo |
Ogni proprietà dichiarata appare in required |
| Nullable esplicito | I campi facoltativi sono union ["...", "null"] |
additionalProperties: false |
Su ogni oggetto, non solo la radice |
Zero $ref / allOf / if-then-else |
Schema completamente espanso |
| Limiti rispettati | ≤ 5000 proprietà, ≤ 10 livelli, ≤ 120k caratteri |
| Vincoli inefficaci spostati | pattern/format verificati lato applicazione |
Gestione refusal |
Il codice distingue rifiuto da errore di schema |
| Test con richiesta reale | Risposta di prova validata prima del deploy |
Se vuoi capire perché additionalProperties: false è così centrale, l'analisi approfondita del keyword additionalProperties mostra come ogni oggetto aperto dilata lo spazio di generazione. Per integrare lo schema in una pipeline CI con test di contratto automatici, il flusso descritto in JSON Schema contract testing evita regressioni silenziose. E se hai bisogno di generare uno schema a partire da esempi JSON esistenti, lo strumento di conversione in JSON Schema della piattaforma ti fa partire da casi reali — anche se, per strict mode, dovrai comunque applicare la riscrittura descritta sopra.
FAQ
Perché la documentazione dice che tutti i campi devono essere required, anche quelli facoltativi?
Perché l'automa a stati finiti deve decidere in anticipo quando ogni chiave è legale. La "facoltatività" si esprime con null, non con l'assenza della chiave: la union nullable è il modo ufficiale per dirlo.
Lo schema viene accettato ma il pattern non funziona. È un bug?
No. In strict mode pattern, minLength, maximum e format non sono applicati dalla grammatica di generazione. Lo schema è sintatticamente valido ma il vincolo non esiste: verifica lato applicazione.
Posso usare $ref se dichiaro anche $defs?
No, in entrambi i casi è vietato. Lo schema deve essere un albero unico, completamente espanso. Gli script di riscrittura automatica risolvono l'espansione.
Qual è la differenza tra refusal e un errore di schema? Il refusal è una risposta conforme in cui il modello dichiara semanticamente di non voler eseguire il compito. Un errore di schema è un 400 all'invio o output non conforme. Sono problemi diversi con rimedi diversi.
Quanto profondo posso annidare gli oggetti? Massimo 10 livelli di annidamento e 5000 proprietà totali per schema. Gli schemi generati automaticamente spesso superano questi limiti: controlla prima dell'invio.
Conclusione
La modalità strict non è un'opzione cosmetica: è il passaggio da "spero che il modello rispetti lo schema" a "la grammatica impedisce fisicamente output non conformi". Il prezzo è un sottoinsieme rigido di JSON Schema — required completo, oggetti chiusi, niente riferimenti — e alcuni vincoli che passano inosservati ma non vengono applicati. Investi mezz'ora nella riscrittura con lo script make_strict, marca le union nullable con criterio, e testa sempre con una richiesta reale prima del deploy: la pipeline che ne risulta è qualitativamente diversa da una costruita con retry e correzioni a posteriori.