JSON Toolkit

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.

Intermedio~8 min di letturaPubblicato il 2026-11-19Aggiornato il 2026-11-19
Schema delle regole di riscrittura JSON Schema per la modalità strict dei LLM

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.

Riferimenti

Articoli correlati

Test contrattuali JSON Schema: salda le regole di validazione nella CI

Uno schema non finisce quando è scritto — lì inizia il degrado. Un refuso rilassa la validazione in silenzio, un refactoring rompe tutte le fixture. Questa guida illustra un'impostazione di test contrattuali attuabile: fixture positivi, negativi e snapshot, lint dello schema stesso, compilazione una tantum riutilizzata e quattro porte CI che trasformano la rottura del contratto in una build rossa.

Intermedio~8 min di letturaAggiornato il 2026-11-05

Il JSON dell'LLM è troncato: prima guarda il motivo di arresto, poi parla di riparazione

Il JSON restituito dal modello manca della chiusura e il parser offre solo un numero di colonna: aggiungere le parentesi fa girare il codice, ma il buco finisce nascosto nei dati. Questo articolo traccia il confine tra ciò che si può riparare e ciò che richiede un retry negli scenari di troncamento: diagnosi dal motivo di arresto, dimensionamento dell'output su p99, ordinamento dei campi dello schema e divulgazione onesta del recupero parziale.

Pratico~5 min di letturaAggiornato il 2026-11-14

Senza additionalProperties, la validazione dello schema non valida nulla

Una validazione superata non significa dati puliti. Pydantic ignora i campi sconosciuti per impostazione predefinita, Zod li rimuove, Ajv li lascia passare — parametri allucinati e chiavi sbagliate attraversano in silenzio. L'articolo mostra le tre forme di accettazione silenziosa e fornisce ricette complete: chiudere gli oggetti, controllare la coercizione, serrare ogni livello di annidamento.

Intermediate~8 min di letturaAggiornato il 2026-11-02