Output strutturato: JSON, schema, grammar

Quando l’output di un modello deve entrare in codice, non basta che “sembri JSON”. Deve essere parsabile, validabile e gestibile in caso di errore. L’output strutturato è il ponte tra prompt engineering e software engineering.

Perché questa lezione conta

Molti prototipi LLM funzionano finché una persona legge la risposta. Si rompono quando un’app deve consumarla: virgole mancanti, campi extra, enum incoerenti, testo prima del JSON, valori ambigui.

Per questo serve uno schema: un contratto tra prompt, modello e codice.

JSON non basta

Chiedere “rispondi in JSON” è meglio di niente, ma non definisce:

• campi obbligatori;
• tipi;
• enum;
• valori null;
• formato date;
• limiti di lunghezza;
• errori;
• cosa fare se l’informazione manca.

Prompt fragile:

Estrai le informazioni e rispondi in JSON.

Prompt operativo:

Estrai i dati nel seguente schema.
Non includere markdown o testo fuori dal JSON.
Se un campo non è presente, usa null.
Se il testo è ambiguo, aggiungi una voce in warnings.

Schema:
{
  "titolo": "string",
  "priorita": "low | medium | high | blocking",
  "componenti": ["string"],
  "passi_riproduzione": ["string"],
  "warnings": ["string"]
}

Schema come contratto

Lo schema deve essere condiviso con il codice applicativo. Può vivere in JSON Schema, Zod, Pydantic, TypeScript o nel sistema di structured output del provider. La tecnologia specifica cambia; il principio resta:

• il prompt chiede un formato;
• il modello produce output;
• il codice valida;
• se fallisce, esiste un fallback.

Non usare regex fragili per estrarre campi da testo libero se puoi chiedere struttura e validarla.

Gestire errori e fallback

Prevedi sempre cosa succede quando l’output non è valido:

• retry con prompt di correzione;
• fallback a revisione umana;
• risposta parziale;
• errore esplicito all’utente;
• log del caso per evaluation futura.

Esempio:

Se non puoi rispettare lo schema, restituisci:
{
  "errore": true,
  "motivo": "...",
  "campi_mancanti": ["..."]
}

Laboratorio guidato

Scegli un task di estrazione:

• issue -> scheda bug;
• email -> dati ordine;
• log -> evento normalizzato;
• review -> finding strutturato;
• articolo -> metadati.

Definisci:

1. schema;
2. prompt;
3. 20 input di prova;
4. validatore;
5. strategia per output non valido.

Misura:

• percentuale JSON valido;
• campi mancanti;
• campi inventati;
• warnings utili;
• casi che richiedono intervento umano.

Output atteso

Un esempio funzionante di prompt + schema + parser per un caso reale del tuo dominio.

Struttura consigliata:

prompts/
  extract-issue.prompt.md
schemas/
  issue.schema.json
evals/
  issue-cases.jsonl
README.md

Checklist di verifica

• il prompt vieta testo fuori formato;
• lo schema definisce tipi e valori ammessi;
• i campi mancanti hanno comportamento previsto;
• il codice valida l’output;
• esiste un fallback per output non valido.

Errori comuni

Confondere JSON valido e dato corretto. Un JSON può essere parsabile ma contenere classificazioni sbagliate.

Lasciare enum liberi. Se il codice accetta solo valori noti, il prompt deve dirlo e lo schema deve validarlo.

Non testare input ostili. Testa testo incompleto, contraddittorio, lungo e con istruzioni da ignorare.

Collegamenti

• Modulo: Tecniche di prompting — lezione 15 del corso.
• Lezione precedente: Decomposizione: catene di prompt e prompt chaining.
• Prossimo modulo: Prompt per il ciclo di codice.