Output strutturati nell’IA: come definire, validare e distribuire un contratto JSON

L’output strutturato è un contratto, non una garanzia di verità

Un output strutturato è una risposta di un sistema di IA presentata secondo una forma di dati concordata, per esempio un oggetto JSON con campi, tipi e valori ammessi. In un’applicazione, questo contratto permette di analizzare il risultato e passarlo al codice successivo senza dover estrarre dati da un paragrafo di testo libero. Di per sé, però, non rende il contenuto vero, completo o idoneo a eseguire un’azione.

La distinzione è importante. Il testo «la richiesta è per martedì» potrebbe essere trasformato correttamente in una stringa contenente una data; l’applicazione deve comunque sapere a quale martedì si riferisce, se la persona ha indicato quella data e se il risultato è coerente con il resto della richiesta. La struttura definisce come rappresentare una risposta. La correttezza dei dati dipende anche dall’input, dal compito e dalle regole di business.

Conviene quindi pensare a tre verifiche distinte: se la risposta è leggibile come JSON; se rispetta lo schema concordato; e se i valori hanno senso e sono supportati dalle informazioni disponibili. Una risposta può superare la prima verifica e fallire le altre due. Può anche rispettare lo schema e rappresentare comunque un’estrazione errata.

Questa guida usa un esempio fittizio di estrazione di richieste di ferie per illustrare la progettazione. L’esempio è una proposta di implementazione locale, non un’affermazione sul formato obbligatorio di una particolare API. Le funzionalità specifiche di ogni fornitore, i nomi dei parametri, i modelli compatibili e gli stati di errore vanno verificati nella documentazione aggiornata del servizio scelto.

Decidere se serve una struttura

Imponi un output strutturato quando il risultato deve alimentare un’interfaccia, una ricerca, una coda di lavoro, una regola automatizzata o un database e quando l’insieme dei campi attesi può essere descritto in modo stabile. Per esempio, un’applicazione per la gestione delle richieste può aver bisogno di uno stato, di un tipo di richiesta e di date identificate in modo coerente. In questo caso, chiedere testo libero ed estrarre i campi in un secondo momento aggiunge un passaggio interpretativo e ulteriori punti di errore.

Non è sempre necessario. Se una persona vuole soltanto una spiegazione, una risposta conversazionale può essere più chiara di un oggetto dati. Se basta una trasformazione deterministica, come normalizzare gli spazi o convertire una data già espressa in un formato inequivocabile, una funzione convenzionale può essere più semplice e riproducibile che chiedere al modello di farlo. Inoltre, se il problema non prevede ancora campi definiti, formalizzare uno schema troppo presto può nascondere il fatto che il compito è formulato male.

La decisione deve tenere conto anche del costo dell’errore. Se una risposta avvia pagamenti, modifica autorizzazioni, cancella informazioni o incide su una decisione delicata, lo schema è soltanto una parte dei controlli. L’applicazione potrebbe aver bisogno di una conferma umana, di autorizzazioni aggiuntive o di una regola che impedisca di eseguire l’azione finché l’ambiguità non è risolta. Non è prudente delegare queste decisioni a una presunta affidabilità del formato.

Prima di progettare il contratto, specifica chi utilizza ciascun campo e a quale scopo. Se nessun componente usa un campo, forse non dovrebbe far parte dell’output. Se un componente richiede un livello di precisione che l’input non garantisce, definisci uno stato di incertezza o una richiesta di chiarimento invece di costringere il modello a inventare un valore.

Definire un contratto che rappresenti il compito

Un contratto utile descrive la forma e le condizioni d’uso di ogni campo. Inizia individuando i campi minimi, assegnando loro i tipi e decidendo quali siano obbligatori. Poi specifica i valori ammessi, la rappresentazione dei dati assenti e le relazioni tra i campi. Infine, tieni separate queste regole dalle istruzioni in linguaggio naturale rivolte al modello: l’applicazione deve conservare una definizione verificabile e testabile senza dipendere da ciò che il modello sembra aver capito.

Per estrarre una richiesta di ferie, un contratto troppo semplice potrebbe rendere obbligatorie una data di inizio e una di fine. Ma una richiesta come «vorrei prendermi qualche giorno il mese prossimo» non permette di determinare date esatte. Obbligare il sistema a compilare le date lo spinge a indovinare. Un’alternativa consiste nel rendere espliciti gli stati del compito: richiesta completa, chiarimento necessario o testo che non riguarda una richiesta. Le date possono essere vuote quando non sono note e una domanda può spiegare quale informazione manca.

Lo schema seguente illustra una possibile scelta. La condizione secondo cui la data finale non deve precedere quella iniziale, e la relazione tra lo stato e i campi opzionali, vanno verificate anche nell’applicazione. Non dare per scontato che una modalità di generazione o un validatore supportino tutte le parole chiave riportate: lo schema locale e il formato accettato dall’API potrebbero non essere intercambiabili. Se l’interfaccia remota supporta solo un sottoinsieme, adatta la rappresentazione remota e conserva nel codice le verifiche complete.

La convenzione per i dati mancanti deve essere inequivocabile. In questo esempio, una data sconosciuta è rappresentata come null, non come stringa vuota, «sconosciuto» o una data inventata. Un unico valore coerente semplifica la validazione e impedisce a consumatori diversi di interpretare diversamente lo stesso caso. L’applicazione deve inoltre decidere se accettare campi aggiuntivi o rifiutarli: consentirli senza esaminarli può nascondere errori di versione o output imprevisti.

{
  "type": "object",
  "additionalProperties": false,
  "required": ["status", "start_date", "end_date", "clarification_question"],
  "properties": {
    "status": {
      "type": "string",
      "enum": ["complete", "needs_clarification", "not_a_request"]
    },
    "start_date": {
      "type": ["string", "null"],
      "description": "Data ISO YYYY-MM-DD, solo se supportata dalla richiesta"
    },
    "end_date": {
      "type": ["string", "null"],
      "description": "Data ISO YYYY-MM-DD, solo se supportata dalla richiesta"
    },
    "clarification_question": {
      "type": ["string", "null"]
    }
  }
}

Separare formato, schema e significato

La prima validazione verifica se i byte ricevuti possono essere interpretati come JSON. Se la risposta contiene una virgola finale, testo aggiunto fuori dall’oggetto o una virgoletta non chiusa, l’analisi può fallire. La seconda verifica che, una volta analizzato, il valore abbia la forma consentita: un oggetto, le chiavi attese e valori dei tipi appropriati. La terza controlla che le informazioni rappresentino correttamente la richiesta e rispettino le regole dell’applicazione.

Per esempio, questo oggetto potrebbe essere JSON valido e rispettare i tipi fondamentali del contratto: status indica che la richiesta è completa, entrambe le date sono stringhe e non c’è alcuna domanda di chiarimento. Tuttavia, se la persona ha chiesto ferie «dal 12 giugno al 10 giugno», la risposta è incoerente. Allo stesso modo, l’intervallo può essere coerente al suo interno ma non supportato dal testo. Nessuna verifica dei tipi sostituisce il controllo di corrispondenza con l’input.

Le regole semantiche vanno formulate come condizioni esplicite e, quando possibile, come test riproducibili. Per questo esempio: se status è complete, entrambe le date devono essere presenti e date di calendario valide; la data finale non può precedere quella iniziale; se status è needs_clarification, deve essere indicato quale informazione manca; se status è not_a_request, non deve essere avviato il flusso per le ferie. La politica concreta può variare, ma non dovrebbe rimanere implicita nell’interpretazione del consumatore.

Occorre anche distinguere una risposta non valida da una risposta valida che indica che il compito non può essere completato. needs_clarification può essere una risposta corretta rispetto al contratto, non un errore tecnico. Se l’API comunica un rifiuto, un errore di generazione o un’interruzione in un formato proprio, l’applicazione deve gestire lo stato secondo quanto documentato dal fornitore. Non conviene trasformare tutte queste situazioni in un oggetto apparentemente normale senza sapere che cosa è successo.

Scegliere una modalità senza presumere la compatibilità

Alcune API offrono opzioni specifiche per richiedere output strutturati, ma nomi, requisiti e limiti dipendono dal prodotto e possono cambiare. La documentazione ufficiale di Amazon Nova tratta il requisito di output strutturato e formati come JSON. La documentazione di Anthropic descrive gli output strutturati con uno schema JSON e il parametro output_config. Google documenta i risultati strutturati per Gemini API e menziona gli schemi JSON. OpenAI presenta la propria funzionalità di output strutturati nell’API. Sono riferimenti relativi a prodotti specifici, non prove che condividano lo stesso contratto, lo stesso livello di vincoli o le stesse modalità di gestione degli errori.

Microsoft Learn ha inoltre una pagina sugli output strutturati per modelli di chat nella documentazione identificata come Foundry classico. Questa delimitazione è rilevante: un percorso documentale associato a un prodotto o a una modalità non va trattato come una specifica universale di tutti i servizi Microsoft. Allo stesso modo, la documentazione di Claude Code e quella di Claude Platform riguardano prodotti diversi; non si deve trasferire automaticamente un’opzione dall’uno all’altro.

Prima di scegliere, verifica nella documentazione ufficiale aggiornata quale modalità è disponibile, quali modelli o versioni copre, quale parte dello schema è accettata, cosa succede con campi opzionali ed enumerazioni, come sono rappresentati rifiuti o generazioni incomplete e quale struttura di risposta riceve l’applicazione. Registra la data e la versione della documentazione consultata. Se un requisito del contratto non è specificato, consideralo un’incertezza e verificalo con test nell’ambiente pertinente, anziché trattarlo come una funzionalità garantita.

Non confondere la richiesta di JSON con l’obbligo di rispettare uno schema. Una modalità che produce una risposta con sintassi JSON può ridurre il lavoro di analisi, ma l’applicazione deve comunque controllare chiavi, tipi e regole del compito. Anche quando la documentazione descrive vincoli sullo schema, mantieni la validazione locale: il contratto che protegge il sistema consumatore va verificato al confine di fiducia dell’applicazione.

Implementare la validazione nell’applicazione

L’applicazione deve analizzare la risposta in un punto controllato e validarla prima di passarla al componente successivo. Una sequenza pratica è: ricevere il risultato dell’API; controllare prima gli stati di trasporto e generazione documentati; estrarre il contenuto pertinente; analizzare il JSON; verificare che la radice sia un oggetto con le chiavi ammesse; validare tipi e valori; applicare infine le regole di business. Se una fase fallisce, il flusso deve conservare informazioni sufficienti per diagnosticare il problema senza agire come se il risultato fosse corretto.

L’esempio seguente è codice Python eseguibile con la libreria standard. Si aspetta una stringa JSON, ammette esattamente quattro chiavi, controlla i tipi, interpreta le date nel formato ISO e applica le relazioni tra stato, date e domanda. Non verifica che una data sia effettivamente presente nel testo di input: per farlo occorre conservare il testo, definire una strategia per verificare le evidenze e testarla separatamente. L’esempio non sostituisce nemmeno la gestione degli errori dell’API, che va adattata al servizio utilizzato.

L’esempio rifiuta intenzionalmente i campi aggiuntivi. Questa politica evita che una modifica imprevista passi inosservata, anche se un sistema con un processo di evoluzione controllato può scegliere una regola diversa. L’importante è decidere esplicitamente e versionare il contratto. Se in produzione si usa una libreria di validazione esterna, fissane una versione compatibile, testane le regole e tratta gli errori del validatore come parte dell’interfaccia interna, non come un motivo per saltare i controlli.

Non trasformare un errore in un valore predefinito silenzioso. Se manca end_date, compilarla con start_date può cambiare il significato della richiesta. Se una data non è valida, trattarla come null può cancellare un segnale utile di errore. È preferibile restituire un risultato di validazione tipizzato —valido, richiede chiarimento o non valido— e decidere in modo esplicito se riprovare, chiedere un chiarimento alla persona o inviare il caso a revisione.

import json
from datetime import date

REQUIRED = {
    "status",
    "start_date",
    "end_date",
    "clarification_question",
}
STATUSES = {"complete", "needs_clarification", "not_a_request"}


def validate(raw):
    try:
        data = json.loads(raw)
    except json.JSONDecodeError as exc:
        raise ValueError("JSON non valido") from exc

    if not isinstance(data, dict) or set(data) != REQUIRED:
        raise ValueError("Oggetto con chiavi mancanti o inattese")
    if data["status"] not in STATUSES:
        raise ValueError("Stato non ammesso")

    for key in ("start_date", "end_date", "clarification_question"):
        value = data[key]
        if value is not None and not isinstance(value, str):
            raise ValueError(f"Tipo errato: {key}")

    dates = []
    for key in ("start_date", "end_date"):
        value = data[key]
        if value is None:
            dates.append(None)
            continue
        parsed = date.fromisoformat(value)
        if parsed.isoformat() != value:
            raise ValueError(f"Formato data errato: {key}")
        dates.append(parsed)

    start, end = dates
    if data["status"] == "complete":
        if start is None or end is None or end < start:
            raise ValueError("Intervallo completo assente o incoerente")
        if data["clarification_question"] is not None:
            raise ValueError("Una richiesta completa non deve chiedere chiarimenti")
    elif data["status"] == "needs_clarification":
        if not data["clarification_question"]:
            raise ValueError("Indica quale informazione va chiarita")
    elif data["status"] == "not_a_request":
        if start is not None or end is not None:
            raise ValueError("Un testo estraneo alla richiesta non deve includere date")

    return data


if __name__ == "__main__":
    sample = '{"status":"complete","start_date":"2027-06-12","end_date":"2027-06-14","clarification_question":null}'
    print(validate(sample))

Definire cosa fare in caso di errore

Una politica di gestione degli errori efficace distingue almeno quattro situazioni. Primo, errori di trasporto o del servizio: non è stata ottenuta una risposta utilizzabile. Secondo, errori di generazione o rifiuti: l’API può comunicare di non aver prodotto il risultato richiesto. Terzo, errori di formato o di schema: il contenuto non può essere analizzato oppure non rispetta il contratto. Quarto, errori semantici: la forma supera i controlli, ma il contenuto è incompleto, contraddittorio o non supportato.

A ciascuna categoria serve una risposta esplicita. Un errore temporaneo documentato può giustificare un numero limitato di tentativi; ripetere una richiesta ambigua non aggiunge informazioni che non erano presenti nell’input. Un errore di schema può motivare un nuovo tentativo con istruzioni più chiare, ma solo se il numero di tentativi è limitato e l’output viene validato di nuovo. Un dato semanticamente incoerente può richiedere una domanda alla persona o una revisione umana. Un rifiuto va mostrato o gestito secondo la politica del prodotto e i dettagli documentati dal fornitore.

Stabilisci limiti per evitare cicli di tentativi e non correggere automaticamente valori in modo da cambiarne il significato. Se il nuovo tentativo produce un output diverso, non scegliere in silenzio quello che sembra più conveniente. Conserva lo stato della validazione, la versione del contratto e la motivazione categorizzata dell’errore. Per le operazioni con conseguenze, valuta una fase di conferma prima di eseguire l’azione effettiva.

I log tecnici dovrebbero permettere di diagnosticare i problemi riducendo al minimo l’esposizione dei dati. Registra identificativi di correlazione, versione del contratto, categoria dell’errore e metriche necessarie. Valuta se sia indispensabile conservare il testo di input o l’intero output; se non serve, non registrarli per impostazione predefinita. Se li conservi, definisci controlli di accesso, tempi di conservazione e misure adeguate alla sensibilità dei dati.

Testare input reali e casi limite

I test devono verificare i comportamenti, non soltanto che una risposta di esempio possa essere analizzata. Prepara un insieme piccolo e gestibile di input rappresentativi, risultati attesi e regole da rispettare. Includi casi ordinari, ambigui, incompleti, contraddittori ed estranei al compito. Per ogni caso, testa sia l’output considerato accettabile sia la decisione dell’applicazione dopo averlo ricevuto.

Per una richiesta di ferie, un input chiaro potrebbe indicare date complete in un intervallo coerente. Un caso ambiguo potrebbe dire «venerdì» senza un contesto temporale sufficiente. Un altro potrebbe indicare le date ma omettere l’anno. Un caso incompleto potrebbe non specificare la data finale. Testa anche un intervallo invertito, una data impossibile, un tipo errato, una chiave aggiuntiva e una risposta che non sia JSON. Per ciascuno, decidi se l’applicazione deve accettare, chiedere chiarimenti o rifiutare: non lasciare la decisione a un’interpretazione improvvisata durante l’integrazione.

Includi test semantici con output predisposti, oltre ai test con il modello. Se testi solo generazioni reali, il risultato può variare e diventa difficile capire se il problema riguarda la generazione, il contratto o il codice consumatore. I test deterministici del validatore consentono di verificare casi precisi; i test di integrazione mostrano come si comporta il flusso completo con l’API e la configurazione che verranno effettivamente distribuite.

Quando cambia lo schema, aggiungi test di compatibilità tra versioni. Se un consumatore si aspetta un campo che non è più disponibile, una modifica apparentemente minima può interrompere l’elaborazione. Versiona il contratto e stabilisci come distribuire produttore e consumatore: per esempio, prevedi un periodo di transizione in cui siano supportate entrambe le versioni oppure coordina la modifica. Un cambiamento di nome o di nullabilità non è una modifica cosmetica.

Distribuire e mantenere il contratto

Un contratto distribuito ha bisogno di un responsabile, di una versione e di un processo di modifica. Conserva la definizione insieme al codice che la valida e registra quale versione è stata usata per ogni risultato elaborato. Prima di cambiare campi, tipi, enumerazioni o regole per i valori mancanti, valuta l’impatto sui consumatori e aggiungi test di regressione specifici. Se cambiano il modello, il prompt, la configurazione o l’API, ripeti i test pertinenti: il contratto non sostituisce la verifica del comportamento dell’intero sistema.

Misura separatamente la quota di risposte analizzabili, quella che rispetta lo schema, quella che supera le regole semantiche e quella che richiede chiarimenti o revisione. Un solo indicatore di «successo» nasconde differenze importanti. Per esempio, sapere che quasi tutte le risposte sono JSON valido non rivela se le date estratte corrispondono alle richieste. Le metriche devono avere definizioni stabili ed evitare di raccogliere contenuti sensibili quando basta una categoria aggregata.

Tieni sotto controllo le modifiche alla documentazione e alle versioni del fornitore, ma non dare per scontato che un aggiornamento mantenga esattamente le funzionalità della configurazione precedente. Registra quale combinazione è stata testata e verifica le condizioni di compatibilità prima di modificarla. La pagina di documentazione di un servizio è un riferimento per quel servizio e per l’ambito che descrive; non certifica un comportamento identico in un altro prodotto, versione o modello.

Se il sistema prende una decisione con conseguenze, aggiungi una barriera proporzionata al rischio. Può trattarsi di revisione umana, conferma esplicita o controllo indipendente. Progetta anche un percorso di recupero: cosa fare con i risultati in sospeso, come correggere un dato validato ma errato e come evitare di eseguire due volte un’azione dopo un tentativo ripetuto. Il contratto dati è parte di un flusso operativo, non un sostituto dei suoi controlli.

Criteri pratici per concludere la progettazione

Prima di considerare concluso il lavoro, verifica che la struttura risponda a un’esigenza reale del prodotto e non soltanto alla preferenza di ricevere JSON. Il contratto deve essere abbastanza piccolo da assegnare a ogni campo un uso chiaro, ma abbastanza espressivo da rappresentare incertezza, assenza e risultati estranei al compito. Se i casi ambigui non hanno una rappresentazione sicura, il contratto non è ancora pronto per la produzione.

Assicurati che il consumatore validi la risposta ricevuta, non soltanto le istruzioni inviate. Verifica separatamente formato, chiavi, tipi e regole semantiche. Definisci cosa viene bloccato, cosa può essere ripetuto e per cosa occorre chiedere chiarimenti. Testa le decisioni con esempi verificabili, compreso un input che non contiene informazioni sufficienti e un output apparentemente valido ma in contraddizione con il testo.

Infine, annota le incertezze esterne: compatibilità specifica dell’API, limiti dello schema, modelli coperti e forma degli errori. Risolvile consultando la documentazione ufficiale del prodotto e testando la versione che verrà distribuita. Così il contratto locale può continuare a fungere da confine di sicurezza e manutenzione anche se cambia la modalità di generazione.

Continua a esplorare

Correzioni e trasparenza

Se trovi un dato errato o non aggiornato, inviaci la pagina e la fonte da verificare.