Il problema
dell'ambiguità nella prosa
Quando scrivi un prompt come fosse una frase normale, lasci spazio a interpretazioni diverse. Il JSON elimina quell'ambiguità: ogni informazione ha un nome preciso e un posto preciso, senza possibilità di equivoco.
Immagina di dare istruzioni a qualcuno scrivendo una lettera (prosa) oppure compilando un modulo con campi ben etichettati (JSON). Il modulo è meno "naturale" da leggere, ma è impossibile fraintendere dove va inserito ogni dato — lo stesso vale per i prompt.
Confronto diretto: stesso obiettivo, due formati
"Scrivimi una descrizione prodotto per delle scarpe da running, abbastanza breve, con un tono che piaccia ai giovani, e magari menziona che sono sostenibili."
{
"prodotto": "scarpe da running",
"lunghezza_parole": 80,
"tono": "giovane, energico",
"punti_da_includere": ["sostenibilità"]
}
Non serve per ogni domanda quotidiana — per una chiacchierata o una domanda semplice, la prosa va benissimo. JSON conviene quando: il prompt ha molti parametri da gestire insieme, vuoi riutilizzare lo stesso prompt cambiando solo alcuni valori, o serve che la risposta sia poi letta da un altro sistema (automazione, foglio di calcolo, database).
Il JSON sembra "tecnico" ma la sua sintassi è più semplice di quanto pensi — in questa guida la imparerai in pochi minuti, senza alcun background di programmazione.
La sintassi base
per chi non programma
JSON ha solo 4 regole fondamentali. Una volta che le conosci, puoi scrivere qualsiasi prompt strutturato.
Regola 1 — Le parentesi graffe {} contengono un oggetto
{ "nome": "Mario" }
Tutto quello che riguarda un singolo "oggetto" (una persona, un compito, un prodotto) va dentro una coppia di parentesi graffe.
Regola 2 — "chiave": valore
Ogni informazione è una coppia: il nome del campo (la "chiave", sempre tra virgolette) seguito da due punti e dal valore.
"tono": "professionale" "lunghezza": 200 "urgente": true
| Tipo di valore | Come si scrive | Esempio |
|---|---|---|
| Testo | Tra virgolette doppie | "professionale" |
| Numero | Senza virgolette | 200 |
| Vero/Falso | Le parole true o false, senza virgolette | true |
Regola 3 — Le parentesi quadre [] contengono una lista
"punti_da_includere": ["sostenibilità", "comfort", "prezzo"]
Quando un campo ha più valori (non uno solo), li elenchi dentro parentesi quadre, separati da virgola.
Regola 4 — La virgola separa, l'ultima coppia non ce l'ha
{ "prodotto": "scarpe da running", "tono": "giovane", "lunghezza_parole": 80 }
Puoi sempre chiedere all'AI stessa: "Aiutami a scrivere questo prompt in formato JSON: [descrivi a parole cosa vuoi]" — l'AI traduce la tua richiesta in JSON corretto, e tu impari guardando l'esempio.
Una virgola di troppo dopo l'ultimo campo (o una mancante tra due campi) rende il JSON "invalido". Se non sei sicuro, scrivi la tua bozza e chiedi all'AI: "Controlla se questo JSON è scritto correttamente" prima di usarlo.
Costruire un
prompt JSON efficace
Un buon prompt JSON separa chiaramente il compito (cosa fare), il contesto (informazioni di sfondo) e il formato di output desiderato.
Le 4 sezioni di un prompt JSON completo
{ "compito": "Descrizione chiara di cosa deve fare l'AI", "contesto": { "settore": "es. e-commerce moda", "pubblico": "es. donne 25-40 anni" }, "vincoli": ["max 100 parole", "tono informale"], "formato_output": "paragrafo unico, senza titoli" }
Esempio reale: brief per un post social
{ "compito": "Scrivi un post Instagram per annunciare un nuovo prodotto", "contesto": { "prodotto": "crema viso idratante alla camomilla", "brand": "NaturaBio", "pubblico": "donne 30-50 anni interessate a cosmetica naturale" }, "vincoli": [ "massimo 80 parole", "includi almeno 3 emoji", "chiudi con una domanda per stimolare i commenti" ], "tono": "caldo, rassicurante, non aggressivo" }
Ogni vincolo è isolato e impossibile da perdere o fraintendere. Se vuoi cambiare solo il prodotto la prossima volta, modifichi un solo campo — il resto della struttura resta identico e collaudato.
Istruzioni di sistema
strutturate in JSON
Quando configuri le istruzioni permanenti di un Progetto (Claude Projects, ChatGPT Projects), puoi scriverle in JSON per renderle più precise e facili da aggiornare nel tempo.
Esempio: istruzioni di progetto per un assistente didattico
{ "ruolo": "Tutor didattico per un corso di Digital Marketing", "pubblico": "studenti principianti, nessuna esperienza tecnica", "tono": "didattico, amichevole, mai condiscendente", "regole": [ "Usa sempre esempi pratici italiani", "Evita gergo tecnico senza spiegarlo", "Se la domanda non riguarda il corso, riporta gentilmente in tema" ], "lunghezza_risposte": "media, mai eccessivamente lunga senza necessità", "lingua": "italiano" }
Come usarlo
- 1Crea un nuovo ProgettoSu Claude o ChatGPT, come visto nella guida comparativa sui Progetti AI.
- 2Incolla il JSON nel campo "Istruzioni personalizzate"Puoi aggiungere una riga introduttiva tipo "Segui sempre queste istruzioni:" prima del JSON.
- 3Testa e aggiusta un campo alla voltaSe qualcosa non funziona come vuoi, modifica solo il campo specifico, non l'intera struttura.
Con istruzioni in prosa, dopo qualche modifica il testo diventa spesso confuso e ripetitivo. Con JSON, puoi aggiungere, rimuovere o modificare singole regole senza mai dover riscrivere tutto da capo.
Strutturare documenti
per una Knowledge Base
Come visto nella guida sul RAG, la qualità di una Knowledge Base conta più della piattaforma usata. Il JSON aiuta a strutturare le informazioni in modo che il sistema le recuperi correttamente.
Esempio: una voce di FAQ strutturata
{ "domanda": "Quali sono i tempi di spedizione?", "risposta": "Le spedizioni in Italia richiedono 2-4 giorni lavorativi.", "categoria": "spedizioni", "varianti_domanda": [ "Quanto tempo ci vuole per la consegna?", "Quando arriva il mio ordine?" ], "ultimo_aggiornamento": "2026-05-01" }
Come visto nella guida RAG, un sistema può rispondere bene a una formulazione ma non a un'altra della stessa domanda. Includere esplicitamente le varianti più comuni nel JSON aiuta il sistema di recupero a collegare correttamente domande diverse alla stessa risposta.
Esempio: scheda prodotto per un catalogo RAG
{ "nome_prodotto": "Crema viso idratante alla camomilla", "categoria": "skincare", "prezzo": 19.90, "ingredienti_chiave": ["camomilla", "acido ialuronico"], "adatto_a": "pelli sensibili e secche", "disponibile": true }
Sia Botpress (caricando il JSON come testo nella Knowledge Base) sia Vertex AI (importando file JSON da Cloud Storage) accettano questo formato — la stessa struttura dati funziona su entrambe le piattaforme viste nella guida sul RAG.
Chiedere all'AI
di rispondere in JSON
Oltre a scrivere il prompt in JSON, puoi chiedere che anche la risposta arrivi in quel formato — utile quando vuoi importare il risultato in un foglio di calcolo o in un altro strumento.
Come chiederlo correttamente
Analizza questa recensione cliente: "[incolla recensione]" Rispondi SOLO in formato JSON, seguendo esattamente questa struttura, senza testo aggiuntivo prima o dopo: { "sentimento": "positivo / negativo / neutro", "punteggio_1_5": numero, "temi_principali": ["lista di temi menzionati"], "richiede_risposta_urgente": true/false }
Specificare esplicitamente che non vuoi testo aggiuntivo prima o dopo il JSON evita che l'AI aggiunga frasi come "Ecco l'analisi:" che romperebbero l'importazione automatica in un altro strumento.
Anche i modelli più recenti possono occasionalmente produrre JSON con piccoli errori di sintassi. Se devi importare la risposta in un sistema automatico, è buona prassi far validare il JSON (puoi chiedere semplicemente: "Verifica che questo JSON sia sintatticamente corretto").
Trasforma un prompt
normale in JSON
In questo esercizio prendi un prompt che useresti normalmente e lo trasformi in formato strutturato.
- Scegli un prompt che usi regolarmente (es. uno dei prompt del Cookbook di Prompt visto in precedenza, o uno tuo).
- Identifica le informazioni variabili (quelle che cambiano ogni volta) separandole da quelle fisse.
- Chiedi all'AI: "Aiutami a trasformare questo prompt in formato JSON strutturato: [incolla il tuo prompt]".
- Rivedi il JSON generato e verifica che ogni informazione sia al posto giusto.
- Usa il nuovo prompt JSON per lo stesso compito e confronta il risultato con quello ottenuto in precedenza con la versione in prosa.
Hai sperimentato il processo di "strutturazione" di un'idea — il passaggio mentale più importante, più della sintassi JSON in sé.
Configura le istruzioni
di un Progetto in JSON
In questo esercizio applichi quanto imparato a un caso reale: le istruzioni permanenti di un Progetto AI.
- Pensa a un Progetto che vorresti creare (es. assistente per le tue lezioni, per le tue campagne marketing).
- Usando il template della sezione 04, scrivi: ruolo, pubblico, tono, regole (almeno 3), lingua.
- Verifica la sintassi chiedendo all'AI di controllarla.
- Crea (o apri) un Progetto su Claude o ChatGPT e incolla le istruzioni JSON.
- Fai 2-3 domande di test pertinenti al tuo caso d'uso.
- Se una regola non viene rispettata, modifica solo quel campo specifico e testa di nuovo.
Questo esercizio riproduce un caso reale: costruire un assistente di progetto che si comporta esattamente come previsto, con istruzioni facili da aggiornare ogni volta che le tue esigenze cambiano.
Prompt JSON per
estrazione dati (caso RAG)
In questo esercizio finale costruisci un prompt che estrae informazioni strutturate da un testo, utile per popolare una Knowledge Base.
- Raccogli 3-5 email o recensioni clienti reali (o chiedi a Claude di generarne di esempio).
- Scrivi un prompt che chiede di estrarre, per ciascun testo, in formato JSON: categoria del problema/richiesta, urgenza (alta/media/bassa), un riassunto in una frase.
- Specifica esplicitamente lo schema desiderato come mostrato nella sezione 06.
- Esegui il prompt e verifica che il JSON restituito sia corretto e completo per ogni testo.
- Immagina come useresti questi dati strutturati: in un foglio Excel? In una lista Microsoft Lists? In una Knowledge Base Botpress?
Una volta collaudato questo prompt, puoi automatizzarlo dentro un flusso Zapier, Make o Power Automate — ogni nuova email arriva, viene analizzata ed estratta in JSON, e i dati confluiscono automaticamente nel tuo sistema di gestione.
Cosa evitare
e tutti i termini spiegati
Gli errori più frequenti per chi inizia, e un glossario completo da consultare quando serve.