OpenAI Structured Outputs — JSON Schema Garantito al 100%

Cos'è: Structured Outputs è la funzionalità annunciata da OpenAI il 6 agosto 2024 che garantisce — con probabilità matematicamente pari al 100% — che la risposta del modello sia conforme a uno JSON Schema fornito dallo sviluppatore. Non è un retry-fino-a-che-non-funziona: è un vincolo applicato durante il sampling stesso, attraverso la generazione di una grammatica context-free derivata dallo schema. Sostituisce l'epoca dei parser euristici con un primitivo deterministico.

Il Problema che Risolve: l'illusione del JSON mode

Prima di agosto 2024, OpenAI offriva due strumenti per output strutturato: il JSON mode (introdotto al DevDay del novembre 2023) che garantiva solo che l'output fosse JSON valido — non che rispettasse uno schema specifico — e il function calling, che usava JSON Schema ma con un tasso di conformità reale stimato attorno al 35-40% sui task complessi. In pratica, ogni applicazione che richiedeva output strutturato robusto era costretta a costruire layer di validazione, retry logic con prompt rinforzati, e fallback per parser tolleranti. Una pipeline data extraction su 10.000 documenti significava centinaia di chiamate fallite da gestire manualmente.

Il problema è strutturale: il modello produce token uno alla volta campionando da una distribuzione di probabilità su tutto il vocabolario. Niente, nel meccanismo di generazione, garantisce che la sequenza prodotta sia un JSON valido — figuriamoci un JSON conforme a uno schema con campi obbligatori, tipi specifici, e vincoli su enum.

Constrained Sampling: la grammatica come vincolo del sampler

La soluzione di OpenAI riprende un'idea già esplorata da progetti open source come Outlines, Guidance e jsonformer: invece di lasciare che il modello produca qualsiasi token e poi validare, si vincola direttamente il sampler a campionare solo token che rispettano la grammatica desiderata. Lo schema JSON fornito viene compilato dinamicamente in una grammatica context-free che descrive l'insieme di tutte le sequenze di token valide. A ogni step di generazione, il sampler maschera i logit dei token che porterebbero a una sequenza non conforme, azzerando la loro probabilità.

Il risultato è matematico: se la grammatica è corretta, è impossibile che il modello produca un output non conforme. Non c'è retry, non c'è validazione a posteriori — la conformità è garantita per costruzione dal meccanismo di sampling stesso. Sui benchmark interni OpenAI riporta 100% di conformità su gpt-4o-2024-08-06 contro circa il 35% del function calling tradizionale.

Strict Mode: l'API e i suoi vincoli

L'attivazione avviene tramite il campo response_format con type: "json_schema" e strict: true. Lo schema viene compilato la prima volta che è inviato — con una latenza di "warm-up" di qualche secondo — e poi cacheato lato server per chiamate successive con lo stesso schema. Per il function calling, lo stesso meccanismo è disponibile aggiungendo strict: true all'oggetto tool, applicando il vincolo agli argomenti delle funzioni.

I vincoli imposti dalla modalità strict sono significativi. Tutti i campi devono essere required: per modellare campi opzionali si deve usare il tipo unione con null (cioè type: ["string", "null"]). additionalProperties deve essere false esplicitamente in ogni oggetto. Non sono supportati alcuni costrutti avanzati: oneOf a livello root, patternProperties, contains, not, e — critico per molti use case — schemi ricorsivi oltre una certa profondità (tipicamente 5 livelli) sono rifiutati. Strutture come alberi di commenti annidati o AST profondi richiedono workaround basati su flat representation con riferimenti ID.

Il Confronto: Anthropic, Outlines, JSON mode

Anthropic con Claude tool use ottiene un tasso di conformità molto elevato (Anthropic non pubblica una percentuale ufficiale ma stime indipendenti la collocano sopra il 95% su gpt-4o-class workload) attraverso un fine-tuning aggressivo e training mirato — ma senza garanzia matematica. È un approccio statistico, non strutturale. Per la maggior parte dei task pratici la differenza è invisibile, ma su edge case rari (input estremamente lunghi, schema complessi, prompt avversariali) i due approcci divergono nel comportamento di failure.

Outlines, libreria open source di Rémi Louf, implementa lo stesso principio di constrained sampling per modelli locali (Llama, Mistral, modelli HuggingFace). È più flessibile — supporta regex, grammatiche custom in formato Lark, schemi ricorsivi senza limiti — ma richiede accesso ai logit del modello, quindi funziona solo con modelli self-hosted o tramite vLLM. È diventato uno standard de facto nell'ecosistema open source per applicazioni che richiedono output strutturato deterministico.

JSON mode (la modalità precedente di OpenAI) resta disponibile per retrocompatibilità ma è di fatto deprecato: garantisce solo JSON valido sintatticamente, non conformità a schema. Il consenso attuale è che strutturare output con strict JSON Schema sia sempre preferibile dove disponibile.

Trade-off e Use Case in Produzione

Il prezzo del 100% di conformità è la latenza di compilazione: la prima chiamata con un nuovo schema può aggiungere 1-3 secondi al time-to-first-token mentre la grammatica viene compilata. Le chiamate successive con lo stesso schema beneficiano del cache e tornano alla latenza normale. Per applicazioni con schemi variabili (es. data extraction dove lo schema dipende dal documento) questa latenza diventa una considerazione architetturale importante — una soluzione comune è pre-warming dei schemi più frequenti all'avvio del servizio.

I casi d'uso ad alto valore in produzione includono: pipeline di data extraction (estrazione di entità strutturate da documenti, contratti, fatture, articoli — dove il vecchio approccio richiedeva validation+retry su ogni chunk), agent state management (gestione dello stato di un agente come oggetto strutturato che evolve a ogni step, con garanzia di shape), structured logging e telemetry (generazione di eventi auditabili in formato fisso per analisi downstream), UI generation (modelli che producono descrizioni di UI come JSON che vengono renderizzate da un client), e traduzione tra formati (es. parsing di natural language requirements in user story strutturate compatibili con Jira/Linear).

La regola pratica emersa nei mesi successivi al lancio è semplice: se il consumer dell'output è codice deterministico, usare strict mode è quasi sempre la scelta giusta. Il piccolo overhead di latenza al primo uso è ampiamente compensato dall'eliminazione di tutto il codice di validazione, retry, e gestione errori che prima era inevitabile.

---