Progettare uno schema JSON

Quando serve la risposta di Claude in una struttura precisa, non analizzi il testo libero sperando che vada tutto bene. Abbini tool_use a uno JSON Schema: Claude compila l'input_schema di uno strumento e l'API garantisce JSON valido con la presenza dei campi richiesti.

In questo modo si eliminano due intere categorie di errori: gli errori di sintassi (virgole mancanti, virgolette non precedute da escape) e i campi mancanti. Lo schema È il contratto: lo progetti bene e il codice a valle non dovrà mai gestire strutture malformate.

Uno "strumento" per l'output strutturato non deve necessariamente chiamare qualcosa. È semplicemente un contenitore denominato il cui input_schema descrive la struttura che si desidera ottenere. Lo definisci, poi leggi ciò che Claude ha inserito nella chiamata allo strumento.

Assegna allo strumento un nome e una descrizione chiari: continuano a determinare la selezione. Il lavoro vero, però, si trova nelle properties dello schema e nell'elenco required.

Se desideri un output strutturato garantito, non lasciare la scelta al caso. Imposta tool_choice per forzare una chiamata allo strumento:

• "auto" — il modello sceglie tra testo e strumento
• "any" — il modello DEVE chiamare uno strumento (garantisce un output strutturato)
• {"type":"tool","name":"X"} — forza l'uso di uno strumento specifico

Per l'estrazione con un singolo schema, forzare lo strumento esatto tramite il nome è il modo più semplice per ottenere una struttura deterministica.

La regola più importante dello schema: contrassegna un campo come required SOLO se è sempre presente nella fonte. Non rendere mai obbligatorio un campo che potrebbe essere assente.

Perché? Un campo obbligatorio costringe il modello a produrre un valore. Se il dato non è presente, Claude ne inventerà uno per rispettare il contratto. Un campo facoltativo ma assente è onesto; un campo obbligatorio ma mancante favorisce le allucinazioni.

Per i campi che possono comparire oppure no — una riga di sconto, un contatto secondario, una data di scadenza — non inserirli in required. Descrivili chiaramente, così Claude li compilerà solo quando i dati esistono davvero.

Una buona descrizione indica al modello il formato dell'input e la regola per l'assenza, così il campo viene omesso invece di essere inventato.

Quando un campo ha un vocabolario fisso — stato, categoria, priorità — usa un enum. In questo modo il testo libero e disordinato ("paid", "PAID", "settled") viene ricondotto a un unico valore canonico su cui il codice può eseguire uno switch.

Gli enum riducono anche le allucinazioni: il modello deve scegliere dall'insieme elencato invece di inventare un'etichetta.

Gli enum rigidi si rompono quando la realtà introduce un nuovo caso. Il modello adottato dagli architetti consiste nell'aggiungere un valore "other" all'enum E un campo detail di testo libero, per registrare ciò che era effettivamente "altro".

In questo modo lo schema rimane valido anche per input imprevisti, non si perdono informazioni e si può analizzare il campo detail per decidere se sia opportuno aggiungere un nuovo valore all'enum.

Le descrizioni dei campi sono mini-prompt. Chiavi vaghe producono output vaghi. Specifica il formato, fornisci un esempio e indica la gestione dei casi limite direttamente nello schema.

È l'equivalente, per l'output strutturato, del principio secondo cui criteri espliciti sono migliori di istruzioni vaghe: "data ISO 8601, ometti se assente" è sempre preferibile a un semplice due_date: string.

Gli schemi ben progettati aiutano a individuare gli errori. Per verificare i calcoli, estrai SIA un valore calcolato SIA un valore dichiarato, poi confrontali nel codice.

Ad esempio, acquisisci stated_total (stampato sul documento) insieme alle voci che puoi sommare autonomamente. Una discrepanza segnala un errore di estrazione o del documento prima che si propaghi ai sistemi a valle.

Lo schema garantisce la struttura del JSON, non la correttezza rispetto alla logica aziendale. Aggiungi una convalida in stile Pydantic. Quando rileva un errore di formato, strutturale o aritmetico, riprova, ma comunica al modello che cosa non ha funzionato.

Invia il documento originale, l'output errato e l'errore di convalida esatto. Questo è il retry con feedback. Nota: riprovare NON aiuta quando l'informazione è semplicemente assente nella fonte: nessuna richiesta ripetuta può far comparire dati mancanti.

Per le estrazioni che dovrai difendere in seguito, progetta campi che conservino la provenienza: l'origine di ogni informazione. Mantieni le associazioni tra affermazioni e fonti: nome della fonte, citazione, pagina o data.

In questo modo un'estrazione a scatola nera diventa verificabile, e puoi annotare valori in conflitto (spesso una differenza di data) invece di sceglierne uno in silenzio.

Punti chiave per progettare uno JSON Schema:

• tool_use + JSON Schema elimina gli errori di sintassi e impone la presenza dei campi richiesti.
• Forza la struttura con tool_choice: "any" per un qualsiasi strumento, {"type":"tool","name":"X"} per uno specifico.
• Indica un campo come required SOLO se è sempre presente: rendere obbligatorio un campo assente provoca invenzioni.
• Usa gli enum per i vocabolari fissi; aggiungi "other" e un campo detail per consentire estensioni.
• Le descrizioni insegnano formato, esempi e gestione dei casi limite.
• Estrai sia i valori calcolati SIA quelli dichiarati per l'autoverifica; convalida, poi riprova con feedback per gli errori di formato, non per le informazioni assenti.
• Acquisisci la provenienza per ottenere un'estrazione verificabile e difendibile.