Un prompt JSON non è una domanda scritta male. È un contratto tra te e l'intelligenza artificiale. Quando dici cosa vuoi in formato strutturato, otterrai quello che chiedi in formato strutturato. Niente ambiguità, niente interpretazioni creative, niente digressioni.

La differenza è tangibile. Una domanda aperta come "Dimmi quali sono i migliori ristoranti di Roma" genera una risposta lunga, narrativa, con opinioni mescolate a fatti. Uno stesso prompt incapsulato in JSON, invece, restituisce una lista ordinata di oggetti con i campi che hai definito tu: nome, indirizzo, categoria, valutazione media, orari di apertura.

Che cos'è uno schema JSON e perché serve

Uno schema JSON è la dichiarazione anticipata di quale struttura deve avere la risposta. Non è una casella dove scrivere il testo libero. È il disegno della casa prima di costruirla. Lo schema specifica: quali campi devono essere presenti, quale tipo di dato contiene ogni campo, se è obbligatorio o facoltativo, quali valori sono ammessi.

Senza schema, chiedi all'AI "dammi i dati dei clienti". La macchina restituisce testo non strutturato, con campi eventualmente mancanti, tipi di dato incoerenti. Con schema, chiedi "restituisci un array di oggetti, ognuno con id numerico, nome testo, email testo, data_iscrizione data, stato scelto tra 'attivo' o 'inattivo'". Quella risposta è parsabile, validabile, importabile direttamente nel database.

Come costruire un prompt JSON: la struttura base

Il primo livello è dichiarare cosa richiedi e in che formato. Anzichè "Mi serve un elenco", scrivi così:

Richiesta in formato strutturato. Voglio una risposta JSON con questa forma esatta: un oggetto con chiave "risultati", il cui valore è un array di oggetti. Ogni oggetto nel array rappresenta un prodotto e contiene: id (numero intero), nome (testo), prezzo (numero decimale), disponibilità (sì o no), categoria (testo scelto tra 'elettronica', 'moda', 'casa').

Questo linguaggio è diretto. Non lascia dubbi. L'AI sa che non stai cercando un paragrafo descrittivo, bensì un file di dati.

Campi obbligatori e optionali

Non tutti i campi hanno lo stesso peso. Alcuni sono essenziali: l'AI deve includerli sempre. Altri sono facoltativi: possono comparire o no.

Nel prompt, distingui i due gruppi. Scrivi: "Campi obbligatori: id, nome, prezzo. Campi facoltativi se disponibili: descrizione, immagine_url, valutazione_media". Così l'AI non inventera i dati mancanti e non lascerà vuoti i campi critici.

Validazione: vincoli e regole

Un prompt JSON solido include vincoli di validazione. Non è "il prezzo deve essere positivo". È "il prezzo è un numero decimale maggiore di zero, con massimo due cifre dopo la virgola".

Oppure: "La categoria deve essere una e una sola fra questi valori: 'A', 'B', 'C'. Niente altre stringhe". Questo impedisce all'AI di improvvisare categorie non previste.

I vincoli riducono il margine di errore. Se l'AI viola uno dei vincoli, lo saprai subito e potrai respingere la risposta.

Esempi concreti di prompt JSON

Supponi di volere un elenco di città italiane con popolazione. Il prompt diretto dice: "Dammi dieci città italiane con la loro popolazione". Vago, narrativo, impreciso.

Il prompt JSON dice: "Restituisci un JSON con questa struttura. Chiave principale: 'città'. Valore: array di esattamente dieci oggetti. Ogni oggetto contiene: nome (testo), regione (testo), abitanti (numero intero, anno di riferimento 2024), coordinate_lat (numero decimale), coordinate_long (numero decimale). Ordina per numero di abitanti decrescente".

Una seconda risposta, più ricca e ordinata, è garantita.

Tipizzazione: il linguaggio comune

La tipizzazione è il vocabolario fra te e l'AI. Non basta dire "numero". Devi dire: numero intero, numero decimale a due cifre, data in formato YYYY-MM-DD, booleano vero o falso, testo massimo 255 caratteri, URL valido.

Ogni specifica riduce l'ambiguità. L'AI non dovrà indovinare il formato: lo conosce in anticipo. La risposta arriva conforme, pronta per essere usata nel codice.

Annidamento e relazioni tra dati

I dati raramente sono piatti. Un ordine contiene cliente, indirizzo, lista di articoli, ognuno con prezzo e quantità. Nel prompt JSON, descrivi questa gerarchia con chiarezza.

Scrivi: "La risposta è un oggetto ordine. Contiene: id, data, e una chiave 'cliente' che è un sotto-oggetto con nome, email, telefono. Contiene anche una chiave 'articoli' che è un array di oggetti, ognuno con id_prodotto, quantità, prezzo_unitario, prezzo_totale".

L'AI comprenderà che deve annidare i dati secondo la logica che hai esposto. La risposta avrà la forma giusta.

Il ruolo dei valori di esempio

Gli esempi non sono decorazione. Sono istruzioni visive. Quando allega un esempio di risposta JSON corretta, l'AI lo usa come modello.

Non è sufficiente dire "Voglio un oggetto con nome e prezzo". È meglio dire: "Voglio un oggetto così: {"nome": "Laptop XPS", "prezzo": 999.99}". L'AI vede la forma esatta e la replica.

Errori comuni nei prompt JSON

Il primo errore è la vaghezza. "Dammi dati sul meteo" senza schema genera testo libero. Con schema, ottieni array strutturati.

Il secondo è l'incoerenza: chiedi in JSON ma non descrivi la forma attesa. L'AI indovina male.

Il terzo è ignorare i vincoli. Se non dici "massimo cinque elementi", l'AI potrebbe restituirne cento. Se non dici "solo numeri positivi", potrebbe includere valori negativi.

Il quarto è dimenticare i tipi. Dire "importo" è vago. Dire "importo numero decimale a due cifre, valuta EUR" è preciso.

Testare e iterare il prompt

Il primo risultato raramente è perfetto. Prova il prompt, controlla se la risposta corrisponde allo schema dichiarato, aggiusta gli elementi che hanno fallito.

Se l'AI omette un campo, aggiungi una frase che lo renda chiaramente obbligatorio. Se lo riempie di dati inventati, aggiungi il vincolo "lascia vuoto se non disponibile". Se il formato è quasi giusto ma non abbastanza preciso, spiega meglio il tipo e le regole.

Dopo tre o quattro iterazioni, il prompt funziona. Da quel momento, puoi usarlo decine di volte con risultati coerenti e affidabili.