JSON: quello che vedrai a schermo

Capire

Prima cosa, quella che toglie il novanta per cento della paura: il JSON non lo scriverai mai. Non è una cosa che si impara a fare, è una cosa che ti compare davanti. Lo produce il modulo del tuo sito quando qualcuno lo compila, lo produce il negozio online quando arriva un ordine, lo produce il gestionale quando gli si chiede qualcosa. A te serve una cosa sola: saperlo leggere senza spaventarti, perché è la prima cosa che vedi il giorno in cui apri un'automazione o ti siedi accanto a chi te la sta costruendo.

Le cose da capire sono tre, e non ce n'è una quarta.

1. È un elenco di etichetta e valore. "totale": 214.60 vuol dire «la voce totale vale duecentoquattordici e sessanta». Come una scheda anagrafica: a sinistra come si chiama il dato, a destra quanto vale. Tutto il resto sono queste coppie messe in ordine.
2. Le graffe raggruppano, le quadre elencano. Le parentesi graffe { } tengono insieme le cose che riguardano un'unica scheda — un ordine, un cliente, una spedizione. Le parentesi quadre [ ] contengono più cose una dopo l'altra: tre articoli, cinque righe, dieci allegati. Se vedi le quadre, lì dentro c'è un elenco.
3. Un valore può contenere un altro gruppo. Il valore della voce «cliente» non è una parola: è un'altra scheda intera, con dentro nome, email e telefono. Sono scatole dentro scatole, e basta guardare i rientri per vedere quale sta dentro quale.

Due dettagli di forma, e poi si legge. I numeri si scrivono con il punto e non con la virgola: 214.60 non è duecentoquattordici e sei scritto male, è così che un programma scrive duecentoquattordici e sessanta. E le etichette non hanno accenti né spazi, per questo troverai scritto citta e partita_iva invece di «città» e «partita IVA». Non è sciatteria: è una regola.

Vedere

Renzo Colombo sta dietro al banco della Ferramenta Colombo, a Bergamo, dal 1987. Il negozio online lo ha aperto sua figlia Sofia nel 2024, e a Renzo interessava fino a un certo punto: lui vende viti alle persone che entrano dalla porta. Poi un giovedì di giugno Sofia gli ha girato lo schermo e gli ha fatto vedere che cosa arriva, esattamente, quando qualcuno compra. Renzo ha detto la frase che dicono tutti: «questa roba non è per me».

Non era vero, e per dimostrarlo bastano due colonne. A sinistra c'è come Renzo scriverebbe quell'ordine sul blocchetto delle commissioni, che è una cosa che fa da trentotto anni. A destra c'è come lo scrive il programma. È lo stesso ordine.

Ed ecco l'ordine per intero, così come arriva. Leggilo guardando i rientri: quello che sta più a destra sta dentro qualcosa.

{
  "ordine": "ORD-2026-0413",
  "data": "2026-06-18T10:24:00+02:00",
  "stato": "pagato",
  "cliente": {
    "nome": "Marta Recalcati",
    "email": "m.recalcati@esempio.it",
    "telefono": "+39 340 000 0000",
    "tipo": "privato",
    "partita_iva": null
  },
  "spedizione": {
    "metodo": "ritiro in negozio",
    "indirizzo": null,
    "citta": "Bergamo",
    "note": "Passo giovedì pomeriggio"
  },
  "righe": [
    {
      "codice": "AVV-18V-2B",
      "prodotto": "Avvitatore a batteria 18V con due batterie",
      "quantita": 1,
      "prezzo_unitario": 149.00,
      "totale_riga": 149.00
    },
    {
      "codice": "PUN-SDS-6",
      "prodotto": "Set punte SDS-Plus 6 pezzi",
      "quantita": 2,
      "prezzo_unitario": 22.80,
      "totale_riga": 45.60
    },
    {
      "codice": "SIL-TRA-310",
      "prodotto": "Silicone trasparente 310 ml",
      "quantita": 5,
      "prezzo_unitario": 4.00,
      "totale_riga": 20.00
    }
  ],
  "totale": 214.60,
  "sconto_applicato": false,
  "note_cliente": ""
}

Renzo ci ha messo dieci minuti e alla fine ha fatto l'unica osservazione che conta davvero, guardando due righe che si somigliano: «e questa qui, la partita IVA, perché è scritta in un modo e le note in un altro?». "partita_iva": null vuol dire «qui non c'è niente, e te lo sto dichiarando»: Marta è una privata e la partita IVA non ce l'ha. "note_cliente": "" vuol dire «c'è un testo, ed è vuoto»: la casella esisteva e lei non ha scritto niente. Sono due cose diverse, e la differenza costa soldi. Ci torniamo fra poco.

Facciamolo insieme

1. Scarica il file e aprilo. Guarda il primo ordine per un minuto senza chiedere niente a nessuno, e conta tre cose: quanti gruppi ci sono dentro l'ordine, quante liste, quante righe di merce. Scrivi i tre numeri su un foglio.
2. Copia un ordine intero, dalla prima graffa aperta all'ultima graffa chiusa, e incollalo nella chat con la prima richiesta qui sotto: fatti raccontare in italiano che cosa contiene.
3. Confronta la risposta con i tre numeri che avevi scritto tu. Se combaciano, sai leggerlo — e questa lezione ha già fatto il suo lavoro.
4. Adesso fai il contrario, che è la metà più utile: descrivi a parole un ordine tuo e chiedi il messaggio scritto come lo scriverebbe un programma. Usa la seconda richiesta qui sotto.
5. Guarda dove sono finite le graffe e le quadre in quello che è uscito. È il momento preciso in cui la paura passa: le hai messe tu, senza saperlo, semplicemente raccontando un ordine.
6. Torna al file e apri l'ultimo, ORD-2026-0468. Manca una cosa che c'è in tutti gli altri quattro. Trovala prima di leggere l'errore comune qui sotto: cercarla da solo vale più che leggerla.

Ho una ferramenta a Bergamo con un piccolo negozio online. Non programmo e non ho nessuna intenzione di imparare. Qui sotto c'è il messaggio che il negozio online manda quando arriva un ordine: me l'hanno fatto vedere a schermo e voglio solo capire che cosa c'è scritto.

[qui si incolla l'ordine per intero, dalla prima graffa aperta all'ultima graffa chiusa]

CHE COSA VOGLIO DA TE
1) Raccontami in italiano che cosa contiene questo messaggio, gruppo per gruppo, come se me lo leggessi a voce mentre lo guardo.
2) Dimmi quanti gruppi ci sono dentro l'ordine, quante liste, e quante cose ci sono dentro ogni lista.
3) Fammi l'elenco delle voci che in questo messaggio non hanno un valore vero, e per ognuna spiegami se vuol dire «qui non c'è niente e lo dichiaro», «c'è ma è vuoto» oppure «non esiste proprio». Sono tre cose diverse: voglio capire la differenza su questo esempio.
4) Alla fine, riscrivimi lo stesso ordine come lo scriverei io a mano sul blocchetto del banco, in cinque o sei righe.

REGOLE
- Usa soltanto quello che ti ho incollato: se una voce non c'è, dimmi che non c'è invece di supporla.
- Niente termini da programmatore. Se ne usi uno, spiegalo in mezza riga la prima volta.
- Non darmi la mappa dei percorsi dei campi e non scrivermi codice: adesso mi serve solo capire che cosa c'è dentro.

COM'È FATTO
È una scheda sola — l'ordine — con dentro altre due schede e un elenco.
  · la scheda «cliente»: chi ha comprato (nome, email, telefono, tipo,
    partita IVA)
  · la scheda «spedizione»: come lo riceve (metodo, indirizzo, città, note)
  · l'elenco «righe»: la merce. Dentro ci sono TRE schede, una per articolo,
    tutte fatte allo stesso modo: codice, prodotto, quantità, prezzo
    unitario, totale della riga
Poi, fuori dai gruppi, quattro voci che riguardano l'ordine nel suo
insieme: numero, data, stato, totale, più lo sconto e le note del cliente.

Gruppi: 2. Liste: 1. Cose dentro la lista: 3.

LE VOCI SENZA UN VALORE VERO — e sono di due tipi diversi
  · "partita_iva": null      -> QUI NON C'È NIENTE, E LO DICHIARO.
      Marta è una privata: la partita IVA non ce l'ha. Il programma non ha
      dimenticato il dato, sta dicendo che quel dato non esiste per lei.
  · "indirizzo": null        -> stessa cosa: ritira in negozio, quindi
      l'indirizzo di consegna non serve e viene dichiarato assente.
  · "note_cliente": ""       -> C'È, ED È VUOTO.
      La casella «note» esisteva, il cliente non ci ha scritto niente.
  · "sconto_applicato": false -> attenzione, questa NON è una voce vuota:
      è una risposta, e la risposta è «no». Falso non vuol dire zero e non
      vuol dire mancante.
In questo ordine non c'è nessuna voce del terzo tipo, quella che manca
del tutto.

COME LO SCRIVERESTI SUL BLOCCHETTO
  Ordine 0413 - 18/06 ore 10:24 - pagato
  Marta Recalcati (privata) - 340 000 0000
  Ritira in negozio, passa giovedì pomeriggio
  1 avvitatore 18V 2 batterie ........ 149,00
  2 set punte SDS-Plus 6 pz ........... 45,60
  5 silicone trasparente 310 ml ....... 20,00
  TOTALE 214,60 - nessuno sconto

Adesso il contrario. È il passaggio che a Renzo ha fatto girare la testa nel senso giusto: non ha imparato a scrivere niente, ha raccontato un ordine e ha guardato dove il programma metteva le parentesi.

Adesso facciamo il contrario. Ti racconto a parole un ordine che ho preso al banco stamattina, e tu me lo scrivi come lo scriverebbe un programma, nello stesso identico modo dell'ordine che ti ho incollato prima — stesse etichette, stessa struttura.

L'ORDINE, COME LO DIREI A VOCE
Stamattina 19 giugno, verso le nove e un quarto, è venuto Ivan Bettoni, un privato, mi ha lasciato solo il numero di telefono 035 000 0002 perché l'email non me l'ha data. Ritira lui in negozio, non c'è niente da spedire e non ha lasciato nessuna nota. Ha preso 2 tubi di silicone trasparente da 310 ml a 4 euro l'uno e 1 rotolo di nastro di carta da mascheratura da 50 mm a 2,30. Nessuno sconto. Ha pagato subito.

CHE COSA VOGLIO DA TE
1) Il messaggio scritto come lo scriverebbe il programma.
2) Sotto, riga per riga, che cosa hai messo dove e perché: in particolare dove sono finite le graffe, dove le quadre, e come hai scritto le cose che non ti ho dato.
3) Dimmi che cosa succederebbe domani se questo ordine finisse dentro un'automazione che manda la conferma per email.

REGOLE
- Non inventare niente che non ti ho detto: se un dato non ce l'ho, dichiaralo assente invece di riempirlo.
- Usa le stesse etichette dell'ordine di prima, non inventarne di nuove.

{
  "ordine": "BANCO-2026-06-19-01",
  "data": "2026-06-19T09:15:00+02:00",
  "stato": "pagato",
  "cliente": {
    "nome": "Ivan Bettoni",
    "email": null,
    "telefono": "+39 035 000 0002",
    "tipo": "privato",
    "partita_iva": null
  },
  "spedizione": {
    "metodo": "ritiro in negozio",
    "indirizzo": null,
    "citta": "Bergamo",
    "note": ""
  },
  "righe": [
    {
      "codice": "SIL-TRA-310",
      "prodotto": "Silicone trasparente 310 ml",
      "quantita": 2,
      "prezzo_unitario": 4.00,
      "totale_riga": 8.00
    },
    {
      "codice": "NAS-CAR-50",
      "prodotto": "Nastro di carta da mascheratura 50 mm",
      "quantita": 1,
      "prezzo_unitario": 2.30,
      "totale_riga": 2.30
    }
  ],
  "totale": 10.30,
  "sconto_applicato": false,
  "note_cliente": ""
}

La riga che vale la lezione è "email": null. Renzo non l'aveva chiesta perché al banco l'email non la chiede mai. E la risposta al punto 3 è stata questa: se domani questo ordine finisse dentro un'automazione che manda la conferma per email, quella conferma non partirebbe. Non perché il programma sia rotto, non perché l'automazione sia fatta male: perché quel dato non c'è. È la prima volta che Renzo ha visto una cosa che si rompe *a monte*, nel modo in cui i dati vengono raccolti al banco, e non nel computer.

Perché ha funzionato

• Le due colonne, blocchetto e programma. Mettere accanto la forma che conosci da trentotto anni e quella che ti fa paura da tre secondi è il solo modo in cui il salto avviene davvero. Non è una spiegazione: è un riconoscimento, ed è per questo che regge anche fra sei mesi.
• Contare prima di chiedere — quanti gruppi, quante liste, quante righe — trasforma la lettura in una verifica. Se i tuoi tre numeri combaciano con quelli della risposta, sai leggerlo; e lo sai perché l'hai fatto tu, non perché qualcuno te l'ha detto.
• Chiedere le voci senza valore vero, divise in tre tipi, è il pezzo che nessuno pensa a chiedere e l'unico che poi produce danni. Nel messaggio di Marta ce ne sono tre, di due tipi diversi, e nella risposta si vedono affiancate — che è l'unico modo per capire la differenza.
• Il divieto di dare la mappa dei percorsi ha tenuto la risposta dentro il compito. Senza quella riga arriva l'elenco dei percorsi tecnici dei campi, che è la lezione giusta al momento sbagliato: utilissima per chi sta costruendo un'automazione, inutile per chi sta imparando a non aver paura di uno schermo.
• Il giro al contrario — racconta e guarda che cosa esce — costa dieci minuti e sostituisce un corso intero. Le graffe non le hai imparate: le hai viste comparire intorno a cose tue.
• «Se un dato non ce l'ho, dichiaralo assente invece di riempirlo» è quello che ha prodotto "email": null invece di un indirizzo verosimile. Un'email inventata dentro un messaggio d'ordine non dà nessun errore oggi: lo dà il giorno in cui parte una conferma verso una casella che non esiste.

Prova tu

Il modello pronto

Ho {{LA TUA ATTIVITÀ}} a {{CITTÀ}}. Non programmo. Qui sotto c'è il messaggio che {{CHI LO MANDA: il modulo del sito, il negozio online, il gestionale, il sistema di pagamento}} produce quando {{QUANDO SUCCEDE}}: voglio solo capire che cosa c'è scritto.

{{INCOLLA QUI IL MESSAGGIO, DALLA PRIMA GRAFFA APERTA ALL'ULTIMA GRAFFA CHIUSA}}

CHE COSA VOGLIO DA TE
1) Raccontami in italiano che cosa contiene, gruppo per gruppo, come se me lo leggessi a voce mentre lo guardo.
2) Quanti gruppi ci sono, quante liste, e quante cose dentro ogni lista.
3) L'elenco delle voci che non hanno un valore vero, divise nei tre tipi: «qui non c'è niente e lo dichiaro», «c'è ma è vuoto», «non esiste proprio». Per ognuna dimmi quale delle tre è.
4) Riscrivimelo come lo scriverei io a mano su un foglio, in cinque o sei righe.
5) Dimmi quali di queste voci potrebbero mancare in un altro messaggio dello stesso tipo, e che cosa si romperebbe se qualcuno ci costruisse sopra {{CHE COSA CI FARESTI: un'email di conferma, una riga in un foglio, un avviso}}.

REGOLE
- Usa soltanto quello che ti ho incollato: se una voce non c'è, dimmi che non c'è invece di supporla.
- Niente termini da programmatore: se ne usi uno, spiegalo in mezza riga.
- Non darmi la mappa dei percorsi dei campi e non scrivermi codice.

Errore comune

Livello successivo

Prendere quei campi e trasformarli in dati che un passo successivo può usare — il percorso esatto di ciascuno, il valore di riserva quando manca, il messaggio ripulito da mandare avanti — è la lezione sul JSON del corso «Automazioni con l'AI».