Ottenere JSON dall'IA: dati strutturati affidabili

Chiedi all'IA di estrarre le informazioni di una fattura «in JSON», e lei risponde: «Certo! Ecco il JSON richiesto», seguito da un blocco di codice, poi da una nota che spiega le sue scelte. Il giorno dopo, il campo importo si chiama totale, la data passa in lettere e il prezzo diventa "125,50 €", una stringa di caratteri. Per una persona è leggibile. Per uno script o un foglio di calcolo è un guasto.

JSON è un formato testuale che ordina i dati in coppie nome e valore. Non serve saper programmare per approfittarne, e se la tua destinazione è un foglio di calcolo, il CSV sarà ancora più semplice. In entrambi i casi, il principio resta lo stesso: decidi il formato in anticipo, senza margine di interpretazione.

Descrivere lo schema invece di dire «in JSON»

La parola «JSON» da sola lascia il modello libero di scegliere struttura, nomi e tipi. Bisogna dargli lo stampo completo. Prendi un ristoratore che vuole tenere sotto controllo le fatture dei fornitori.

Prima:

Estrai le informazioni da questa fattura in JSON.

Dopo:

Estrai i dati dalla fattura qui sotto. Rispondi esclusivamente con un oggetto JSON valido, senza testo prima né dopo e senza tag di codice Markdown.

Rispetta esattamente questa struttura e questi nomi di campo:

{
  "fornitore": "stringa",
  "numero_fattura": "stringa",
  "data": "AAAA-MM-GG",
  "totale_imponibile": numero,
  "totale_ivato": numero,
  "righe": [
    { "descrizione": "stringa", "quantita": numero, "prezzo_unitario_imponibile": numero }
  ],
  "categoria": "bevande" | "freschi" | "dispensa" | "altro"
}

Regole:
- I numeri si scrivono con il punto decimale, senza simbolo di valuta.
- Se un'informazione è assente o illeggibile, metti null. Non indovinare mai e non calcolarla.
- Non aggiungere nessun campo.

Fattura:
[TESTO DELLA FATTURA]

Quattro scelte fanno la differenza. Lo schema è mostrato per intero, quindi i nomi dei campi non si spostano più. La data ha un formato non ambiguo: 2026-03-04 non si confonde da un paese all'altro. La categoria è un elenco chiuso, il che evita di avere «Bevande», «bevanda» e «Vini» nello stesso file. Infine, il null dà all'IA una via d'uscita onesta quando l'informazione manca.

I campi mancanti, fonte della maggior parte degli errori

Quando un campo è obbligatorio nel tuo schema e l'informazione non è nel documento, il modello tende a produrne una. Può comparire una partita IVA dove non ce n'era. Il JSON sarà perfettamente valido e sbagliato.

Due precauzioni aiutano. La prima è la regola del null vista sopra, per ogni campo. La seconda è chiedere la prova quando la posta in gioco lo giustifica: aggiungi un campo estratto_fonte che ricopia il passaggio da cui viene il valore. Puoi allora confrontare rapidamente su un campione. Per la logica generale, l'articolo per ridurre le allucinazioni va più a fondo.

Il caso più comune: un CSV per Excel

Se la tua destinazione è un foglio di calcolo, dimentica JSON: chiedi direttamente un CSV. Una difficoltà da conoscere: con le impostazioni regionali italiane, Excel si aspetta in genere il punto e virgola come separatore e la virgola per i decimali. Un CSV con le virgole può quindi aprirsi con tutto in un'unica colonna.

Esempio per la tesoriera di un'associazione che trasforma iscrizioni ricevute via e-mail, qui con dati fittizi:

Trasforma i messaggi qui sotto in una tabella CSV, senza alcun testo intorno e senza tag di codice.

Parametri:
- separatore: punto e virgola ;
- decimali: virgola ;
- prima riga, esattamente: nome;cognome;attivita;importo;metodo_pagamento;da_verificare
- attivita: tra [ELENCO DELLE ATTIVITÀ]
- metodo_pagamento: assegno, bonifico, contanti oppure vuoto se non precisato.

Una riga per persona iscritta. Se un messaggio iscrive due persone, fai due righe. Se un'informazione è assente o ambigua, lascia la cella vuota e metti «sì» in da_verificare.

Messaggi:
[INCOLLA I MESSAGGI]

Incolla il risultato in un file .csv, o nel tuo foglio di calcolo passando dalla funzione di importazione del testo. Attenzione ai dati personali: prima di incollare i messaggi di persone reali, guarda che cosa non mettere in un chatbot e le condizioni del tuo piano.

Convalidare il risultato, ogni volta

Un output strutturato può rompersi in tre modi: il testo non è un JSON valido, la struttura non corrisponde allo schema, oppure i valori sono sbagliati. I primi due si controllano automaticamente. Ecco un breve script Python che si ferma non appena compare un problema:

import json

CAMPI = {"fornitore", "numero_fattura", "data", "totale_imponibile",
         "totale_ivato", "righe", "categoria"}
CATEGORIE = {"bevande", "freschi", "dispensa", "altro"}

def valida(risposta: str) -> dict:
    dati = json.loads(risposta)  # va in errore se non è JSON
    if set(dati) != CAMPI:
        raise ValueError(f"Campi non corretti: {set(dati) ^ CAMPI}")
    if dati["categoria"] not in CATEGORIE:
        raise ValueError(f"Categoria sconosciuta: {dati['categoria']}")
    ivato, imponibile = dati["totale_ivato"], dati["totale_imponibile"]
    if ivato is not None and imponibile is not None and ivato < imponibile:
        raise ValueError("Totale IVA inclusa inferiore al totale imponibile")
    return dati

Il controllo del totale con IVA rientra nel buon senso di mestiere, e intercetta errori che nessuno schema vedrebbe. Per i valori, prevedi un controllo a campione: confronta dieci documenti a mano prima di fidarti dell'elaborazione, poi qualcuno di tanto in tanto.

Senza codice, puoi chiedere al modello di segnalarti le righe sospette in una nuova conversazione, ma può non vederne qualcuna. Una somma ricalcolata nel foglio di calcolo resta più sicura.

Passare all'API quando il volume sale

Se tratti decine di documenti con un programma, il solo prompt non è la soluzione migliore. Le API dei principali fornitori offrono opzioni per vincolare l'output a uno schema JSON. I loro nomi e le loro garanzie evolvono, guarda la documentazione del tuo fornitore nel momento in cui ti ci metti. Queste opzioni ti garantiscono una struttura conforme, non valori giusti: mantieni la regola del null e i controlli di mestiere.

Per un flusso in più passaggi, un output JSON serve anche da ponte tra due modelli o due prompt, come in una catena di prompt.

Fai la prova su tre documenti reali

Scegli tre documenti dello stesso tipo, di cui uno fatto male: una fattura scansionata, un messaggio incompleto. Passali nel prompt che hai scelto con uno schema di soli cinque campi, poi confronta ogni valore con l'originale. Il documento fatto male ti dirà quali regole aggiungere prima di ampliare lo schema.