File JSON di esempio - struttura, sintassi e uso pratico

Quando un’applicazione deve scambiare dati con un database, un’API o una dashboard, la differenza la fa spesso una struttura semplice e coerente. In questa guida mostro un file JSON di esempio, spiego ogni elemento e chiarisco come crearlo, validarlo e usarlo nell’analisi dei dati. Troverai anche un confronto pratico con il formato CSV e gli errori che possono rendere inutilizzabile un documento apparentemente corretto.

Da dove parte un file JSON di esempio

JSON significa JavaScript Object Notation, ma non è necessario conoscere JavaScript per utilizzarlo. Io lo considero soprattutto un formato testuale per organizzare e trasferire dati, leggibile sia dalle persone sia dai programmi.

Un documento può contenere un oggetto racchiuso tra parentesi graffe oppure un array racchiuso tra parentesi quadre. L’estensione più comune è .json, anche se il contenuto resta un normale testo che può essere aperto con un editor, un browser o un ambiente di sviluppo.

{
  "nome": "Laura Bianchi",
  "eta": 34,
  "attivo": true,
  "ruoli": ["analista", "amministratrice"],
  "ultimoAccesso": null
}

In questo caso ogni informazione è una coppia composta da chiave e valore. Le chiavi sono stringhe, mentre i valori possono essere stringhe, numeri, valori booleani, null, oggetti o array.

Le regole essenziali della sintassi

• Le chiavi e le stringhe richiedono virgolette doppie.
• Tra una chiave e il suo valore si usa il simbolo :.
• Le coppie sono separate da virgole, ma l’ultimo elemento non deve avere una virgola finale.
• I valori booleani si scrivono true e false, senza virgolette.
• Il valore nullo si scrive null.
• I commenti non fanno parte dello standard JSON.

Un dettaglio che spesso crea problemi è proprio la virgola finale. In molti linguaggi è tollerata, mentre in JSON standard rende il documento non valido. Per questo preferisco controllare sempre il file con un validatore prima di collegarlo a un’applicazione.

Un esempio completo con dati provenienti da un database

Per capire davvero il formato, conviene osservare una struttura simile a quella usata in un piccolo progetto di business intelligence. Qui il documento contiene informazioni sul report, sul periodo analizzato e su una serie di vendite.

{
  "report": {
    "titolo": "Vendite trimestrali",
    "periodo": {
      "da": "2026-01-01",
      "a": "2026-03-31"
    },
    "valuta": "EUR"
  },
  "vendite": [
    {
      "id": 1001,
      "cliente": {
        "nome": "Alfa Design",
        "citta": "Milano"
      },
      "prodotto": "Licenza Pro",
      "quantita": 3,
      "prezzoUnitario": 249.90,
      "totale": 749.70,
      "pagato": true
    },
    {
      "id": 1002,
      "cliente": {
        "nome": "Beta Consulting",
        "citta": "Roma"
      },
      "prodotto": "Licenza Base",
      "quantita": 5,
      "prezzoUnitario": 99.90,
      "totale": 499.50,
      "pagato": false
    }
  ]
}

L’oggetto principale separa i metadati del report dai record operativi. L’array “vendite” permette di aggiungere nuove righe senza cambiare la struttura generale, mentre l’oggetto “cliente” raggruppa informazioni che appartengono alla stessa entità.

Questa organizzazione è utile quando i dati arrivano da un’API o devono essere consumati da applicazioni diverse. In una dashboard, per esempio, il programma può leggere il periodo dal blocco “report” e calcolare il fatturato usando i valori presenti nell’array.

Per importi monetari reali, però, non mi affiderei sempre ai numeri decimali senza una verifica. Nei sistemi finanziari è spesso più sicuro registrare gli importi in centesimi, come 74970, oppure applicare regole precise di arrotondamento nel database e nell’applicazione.

Oggetti, array e tipi di dato senza confusione

La differenza tra oggetto e array è semplice, ma ha conseguenze pratiche. Un oggetto descrive un’entità tramite proprietà nominate; un array rappresenta una lista ordinata di elementi, che possono essere stringhe, numeri o altri oggetti.

Una lista semplice

{
  "categorie": [
    "Marketing",
    "Vendite",
    "Customer care"
  ]
}

Leggi anche: Operatori logici SQL - AND, OR, NOT e NULL senza errori

Una lista di record

[
  {
    "id": 1,
    "nome": "Notebook",
    "quantita": 12
  },
  {
    "id": 2,
    "nome": "Monitor",
    "quantita": 7
  }
]

Il secondo esempio è frequente nelle risposte delle API. Ogni elemento dell’array ha la stessa forma, quindi può essere trasformato facilmente in righe di una tabella o in un dataframe. Se i record hanno campi troppo diversi tra loro, l’analisi diventa più fragile e richiede trasformazioni aggiuntive.

Come creare, validare e leggere il documento

Per iniziare basta un editor di testo. Creo un nuovo file, salvo il contenuto con codifica UTF-8 e uso un nome descrittivo come “vendite-trimestre.json”. Un editor per sviluppatori è preferibile perché evidenzia parentesi, virgolette e indentazione.

1. Definisco quali entità devo rappresentare, per esempio clienti e ordini.
2. Scelgo nomi coerenti per le chiavi, evitando di alternare “dataOrdine”, “data_ordine” e “ordineData”.
3. Inserisco i valori rispettando i tipi corretti.
4. Controllo il file con un validatore JSON.
5. Lo testo con gli stessi dati e casi limite che userà l’applicazione.

In JavaScript un file può essere letto con JSON.parse() dopo aver caricato il testo. In Python, invece, la libreria standard offre una procedura diretta.

import json

with open("vendite-trimestre.json", encoding="utf-8") as file:
    dati = json.load(file)

print(dati["report"]["titolo"])
print(len(dati["vendite"]))

Il controllo della sintassi non basta a garantire che i dati siano corretti. Un documento può essere formalmente valido ma contenere un prezzo negativo, una data impossibile o un campo obbligatorio mancante. Per progetti condivisi consiglio quindi uno schema JSON, cioè un insieme di regole che descrive campi richiesti, tipi e valori ammessi.

JSON o CSV per l’analisi dei dati

La scelta dipende dalla forma dei dati. JSON è adatto a strutture annidate e a scambi tra sistemi; CSV funziona bene quando si lavora con una tabella regolare composta da righe e colonne.

Se devo trasferire un catalogo con categorie, varianti e immagini, scelgo JSON perché mantiene la gerarchia. Se devo analizzare milioni di righe con poche colonne in un foglio di calcolo, preferisco spesso CSV o un formato colonnare più adatto all’elaborazione.

Gli errori che rendono invalido un JSON

Gli errori più comuni sono piccoli e difficili da individuare a colpo d’occhio. La differenza tra un file che viene importato correttamente e uno che genera un errore può dipendere da una sola virgola o da una coppia di virgolette mancante.

• Virgola finale dopo l’ultimo elemento di un oggetto o di un array.
• Uso di apici singoli al posto delle virgolette doppie.
• Chiavi non racchiuse tra virgolette.
• Valori come True, False o None, tipici di Python ma non validi in JSON.
• Commenti inseriti con // o /* */.
• Date, percentuali o importi scritti in formati diversi nello stesso file.

{
  "nome": "Luca",
  "attivo": true,
  "tag": ["BI", "data science"]
}

Questa struttura è valida. Al contrario, la versione seguente contiene apici singoli e una virgola finale.

{
  'nome': 'Luca',
  'attivo': true,
}

Un’altra attenzione riguarda le date. JSON non possiede un tipo nativo per la data, quindi conviene usare stringhe in formato ISO 8601, come “2026-03-31T14:30:00Z”, e documentare sempre il fuso orario.

Come preparare un JSON affidabile per API e dashboard

Una buona struttura non deve essere soltanto valida, ma anche stabile nel tempo. Prima di pubblicare un endpoint o consegnare un dataset, verifico che i nomi dei campi siano comprensibili, che gli identificativi siano univoci e che il significato di null e campo assente sia stato definito.

Evito inoltre di inserire password, token, dati sanitari o informazioni personali non necessarie. Il JSON è testo leggibile, quindi non offre da solo alcuna protezione. La sicurezza deve essere gestita con autenticazione, autorizzazioni, cifratura e controllo degli accessi.

Per dataset molto grandi, un unico file può diventare lento da caricare e difficile da aggiornare. In quel caso conviene suddividere i dati, usare paginazione nelle API oppure scegliere formati più efficienti per l’elaborazione analitica. La flessibilità del JSON è utile, ma non significa che sia sempre la soluzione più economica in termini di spazio e prestazioni.

Il criterio che uso più spesso è pratico: JSON per scambiare strutture e relazioni tra sistemi, CSV per tabelle semplici, database per dati operativi persistenti. Con nomi coerenti, tipi ben definiti e una validazione automatica, anche un file JSON di esempio può diventare una base solida per integrazioni, report e processi di data science.