File JSON spiegato: Struttura, sintassi e utilizzo pratico

# File JSON spiegato: Struttura, sintassi e utilizzo pratico

I file JSON sono il formato standard per la memorizzazione e lo scambio di dati strutturati. Questa guida completa ti insegnerà tutto ciò che devi sapere sui file JSON, dalla loro struttura di base agli usi avanzati.

Cos'è un file JSON?

Un file JSON è un file di testo con estensione .json che contiene dati strutturati in formato JavaScript Object Notation. È:

• Leggibile dall'uomo: Puoi aprirlo e comprenderlo con qualsiasi editor di testo
• Analizzabile dalle macchine: Facile da leggere e scrivere per i programmi
• Leggero: Dimensione del file ridotta rispetto ad altri formati
• Multipiattaforma: Funziona su tutti i sistemi operativi

Anatomia di un file JSON

Struttura di base

Un file JSON inizia sempre con un elemento radice, che può essere:

Un oggetto (più comune)

Un array

{
  "tipo": "oggetto",
  "descrizione": "Questo è l'elemento radice più comune"
}

o

[
  {
    "tipo": "array",
    "elemento": 1
  },
  {
    "tipo": "array",
    "elemento": 2
  }
]

Regole di sintassi fondamentali

I dati sono in coppie chiave-valore

Le chiavi devono essere stringhe tra virgolette doppie

I valori possono essere di vari tipi

Le coppie sono separate da virgole

Gli oggetti sono racchiusi tra { }

Gli array sono racchiusi tra [ ]

Non sono permesse virgole finali

Non sono permessi commenti

Tipi di dati nei file JSON

String (Stringhe)

{
  "nome": "Mario Rossi",
  "indirizzo": "Via Garibaldi 45",
  "note": "Cliente VIP",
  "emoji": "✨ Caratteri Unicode supportati!"
}

Number (Numeri)

{
  "intero": 42,
  "decimale": 3.14159,
  "negativo": -17,
  "scientifico": 1.5e10,
  "zero": 0
}

Boolean (Booleani)

{
  "attivo": true,
  "verificato": false,
  "premium": true
}

Null

{
  "telefono_secondario": null,
  "note_aggiuntive": null
}

Object (Oggetti)

{
  "utente": {
    "id": 1001,
    "nome": "Laura",
    "cognome": "Bianchi",
    "contatti": {
      "email": "laura@example.com",
      "telefono": "+39 02 1234 5678"
    }
  }
}

Array

{
  "numeri": [1, 2, 3, 4, 5],
  "nomi": ["Marco", "Anna", "Luca"],
  "misto": [1, "testo", true, null, {"oggetto": "valore"}],
  "vuoto": []
}

Esempi di file JSON del mondo reale

1. Configurazione applicazione (config.json)

{
  "applicazione": {
    "nome": "GestionaleAziendale",
    "versione": "2.5.0",
    "ambiente": "produzione",
    "debug": false,
    "porta": 8080,
    "host": "0.0.0.0"
  },
  "database": {
    "tipo": "postgresql",
    "host": "db.example.com",
    "porta": 5432,
    "nome": "azienda_db",
    "utente": "admin",
    "pool": {
      "min": 2,
      "max": 10,
      "timeout": 30000
    }
  },
  "cache": {
    "abilitata": true,
    "driver": "redis",
    "ttl": 3600,
    "prefisso": "app:"
  },
  "logging": {
    "livello": "info",
    "file": "/var/log/app/application.log",
    "rotazione": {
      "frequenza": "giornaliera",
      "massimo_file": 30
    }
  },
  "email": {
    "smtp_host": "smtp.gmail.com",
    "smtp_porta": 587,
    "da": "noreply@example.com",
    "usa_tls": true
  },
  "caratteristiche": {
    "autenticazione_multi_fattore": true,
    "registrazione_utenti": true,
    "notifiche_push": false,
    "modalità_manutenzione": false
  }
}

2. Dati prodotto (prodotti.json)

{
  "prodotti": [
    {
      "id": "PROD-001",
      "nome": "Laptop Professional 15"",
      "categoria": "elettronica",
      "sottocategoria": "computer",
      "prezzo": 1299.99,
      "valuta": "EUR",
      "disponibile": true,
      "giacenza": 45,
      "specifiche": {
        "processore": "Intel Core i7-12700H",
        "ram": "16GB DDR5",
        "storage": "512GB NVMe SSD",
        "schermo": "15.6" Full HD IPS",
        "grafica": "NVIDIA RTX 3060",
        "peso": "2.1kg"
      },
      "immagini": [
        "/images/laptop-001-front.jpg",
        "/images/laptop-001-side.jpg",
        "/images/laptop-001-open.jpg"
      ],
      "recensioni": {
        "media": 4.7,
        "totale": 328,
        "distribuzione": {
          "5_stelle": 245,
          "4_stelle": 62,
          "3_stelle": 15,
          "2_stelle": 4,
          "1_stella": 2
        }
      },
      "tag": ["business", "gaming", "portatile", "alta-prestazione"],
      "produttore": {
        "nome": "TechCorp",
        "paese": "Italia",
        "garanzia_anni": 2
      },
      "sconti": [
        {
          "tipo": "percentuale",
          "valore": 10,
          "inizio": "2026-01-15",
          "fine": "2026-02-15",
          "codice": "WINTER10"
        }
      ]
    },
    {
      "id": "PROD-002",
      "nome": "Mouse Wireless Ergonomico",
      "categoria": "elettronica",
      "sottocategoria": "accessori",
      "prezzo": 49.99,
      "valuta": "EUR",
      "disponibile": true,
      "giacenza": 234,
      "specifiche": {
        "tipo": "wireless",
        "connessione": "Bluetooth 5.0 / USB",
        "dpi": "800-3200",
        "pulsanti": 6,
        "batteria": "ricaricabile",
        "autonomia_ore": 120
      },
      "immagini": [
        "/images/mouse-002-main.jpg",
        "/images/mouse-002-side.jpg"
      ],
      "recensioni": {
        "media": 4.5,
        "totale": 156
      },
      "tag": ["wireless", "ergonomico", "ufficio"],
      "produttore": {
        "nome": "PeripheralPro",
        "paese": "Germania",
        "garanzia_anni": 1
      }
    }
  ],
  "metadati": {
    "totale_prodotti": 2,
    "ultima_modifica": "2026-01-26T10:30:00Z",
    "versione_catalogo": "1.5"
  }
}

3. Profilo utente (utente.json)

{
  "utente": {
    "id": "USR-87654321",
    "informazioni_personali": {
      "nome": "Giulia",
      "cognome": "Ferrara",
      "data_nascita": "1992-05-15",
      "genere": "F",
      "nazionalità": "italiana"
    },
    "contatti": {
      "email_principale": "giulia.ferrara@email.com",
      "email_secondaria": null,
      "telefono_mobile": "+39 345 678 9012",
      "telefono_fisso": null
    },
    "indirizzo": {
      "via": "Corso Vittorio Emanuele II",
      "numero_civico": "78",
      "interno": "A/5",
      "città": "Torino",
      "provincia": "TO",
      "cap": "10121",
      "regione": "Piemonte",
      "paese": "Italia",
      "coordinate": {
        "latitudine": 45.0703,
        "longitudine": 7.6869
      }
    },
    "account": {
      "username": "gferrara",
      "creato_il": "2024-03-10T14:22:00Z",
      "ultimo_accesso": "2026-01-26T09:15:00Z",
      "stato": "attivo",
      "verificato": true,
      "ruolo": "premium",
      "abbonamento": {
        "piano": "Professional",
        "inizio": "2025-01-01",
        "scadenza": "2026-12-31",
        "rinnovo_automatico": true,
        "costo_mensile": 29.99,
        "metodo_pagamento": "carta_credito"
      }
    },
    "preferenze": {
      "lingua": "it",
      "fuso_orario": "Europe/Rome",
      "tema": "scuro",
      "notifiche": {
        "email": true,
        "push": true,
        "sms": false,
        "frequenza": "giornaliera"
      },
      "privacy": {
        "profilo_pubblico": false,
        "mostra_email": false,
        "attività_condivisa": true
      }
    },
    "statistiche": {
      "accessi_totali": 847,
      "ore_utilizzo": 1253,
      "progetti_creati": 34,
      "file_caricati": 892,
      "storage_usato_mb": 4567
    },
    "interessi": [
      "sviluppo-web",
      "design",
      "fotografia",
      "viaggi",
      "tecnologia"
    ],
    "badge": [
      {
        "id": "early-adopter",
        "nome": "Early Adopter",
        "ottenuto_il": "2024-03-10"
      },
      {
        "id": "power-user",
        "nome": "Power User",
        "ottenuto_il": "2025-06-15"
      }
    ]
  }
}

4. Dati API REST (risposta-api.json)

{
  "stato": "successo",
  "codice": 200,
  "messaggio": "Richiesta elaborata con successo",
  "timestamp": "2026-01-26T14:30:45.123Z",
  "dati": {
    "ordine": {
      "id": "ORD-2026-00125",
      "numero": "125",
      "data_ordine": "2026-01-26",
      "stato": "confermato",
      "cliente": {
        "id": "CLI-5678",
        "nome": "Roberto Mancini",
        "email": "roberto.m@example.com"
      },
      "articoli": [
        {
          "id_prodotto": "PROD-001",
          "nome": "Tastiera Meccanica RGB",
          "quantità": 2,
          "prezzo_unitario": 89.99,
          "subtotale": 179.98
        },
        {
          "id_prodotto": "PROD-045",
          "nome": "Cuffie Wireless",
          "quantità": 1,
          "prezzo_unitario": 129.99,
          "subtotale": 129.99
        }
      ],
      "riepilogo": {
        "subtotale": 309.97,
        "sconto": 30.99,
        "iva": 58.89,
        "spedizione": 7.99,
        "totale": 345.86,
        "valuta": "EUR"
      },
      "spedizione": {
        "metodo": "corriere_espresso",
        "stimata": "2026-01-28",
        "indirizzo": {
          "destinatario": "Roberto Mancini",
          "via": "Via Milano 23",
          "città": "Bologna",
          "cap": "40100",
          "telefono": "+39 051 123 4567"
        },
        "tracking": {
          "numero": "IT123456789",
          "url": "https://tracking.example.com/IT123456789"
        }
      },
      "pagamento": {
        "metodo": "carta_credito",
        "stato": "completato",
        "transazione_id": "TRX-98765432",
        "ultimo_4_cifre": "4242"
      }
    }
  },
  "meta": {
    "versione_api": "2.1",
    "tempo_risposta_ms": 45,
    "server": "api-prod-03"
  }
}

Creazione di file JSON

Manualmente con un editor di testo

Apri un editor di testo (VS Code, Notepad++, Sublime Text)

Scrivi il contenuto JSON

Salva con estensione .json

Programmaticamente

JavaScript/Node.js:

const fs = require('fs');

// Oggetto JavaScript
const dati = {
  nome: "Mario",
  età: 35,
  città: "Milano"
};

// Converti in JSON e salva
fs.writeFileSync(
  'output.json',
  JSON.stringify(dati, null, 2), // 2 spazi di indentazione
  'utf8'
);

Python:

import json

# Dizionario Python
dati = {
    "nome": "Mario",
    "età": 35,
    "città": "Milano"
}

# Salva in file JSON
with open('output.json', 'w', encoding='utf-8') as file:
    json.dump(dati, file, indent=2, ensure_ascii=False)

Lettura di file JSON

JavaScript/Node.js

const fs = require('fs');

// Metodo 1: Sincrono
const dati = JSON.parse(fs.readFileSync('dati.json', 'utf8'));
console.log(dati.nome);

// Metodo 2: Asincrono
fs.readFile('dati.json', 'utf8', (err, data) => {
  if (err) throw err;
  const dati = JSON.parse(data);
  console.log(dati);
});

// Metodo 3: Con Promise (moderno)
const datiPromise = fs.promises.readFile('dati.json', 'utf8')
  .then(data => JSON.parse(data))
  .catch(err => console.error(err));

Python

import json

# Leggi file JSON
with open('dati.json', 'r', encoding='utf-8') as file:
    dati = json.load(file)
    print(dati['nome'])

# Gestione errori
try:
    with open('dati.json', 'r') as file:
        dati = json.load(file)
except FileNotFoundError:
    print("File non trovato")
except json.JSONDecodeError:
    print("JSON non valido")

Modifica di file JSON

JavaScript

const fs = require('fs');

// Leggi
let dati = JSON.parse(fs.readFileSync('config.json', 'utf8'));

// Modifica
dati.versione = "2.0.0";
dati.nuova_caratteristica = true;
dati.database.porta = 5433;

// Salva
fs.writeFileSync('config.json', JSON.stringify(dati, null, 2));

Python

import json

# Leggi
with open('config.json', 'r') as file:
    dati = json.load(file)

# Modifica
dati['versione'] = '2.0.0'
dati['nuova_caratteristica'] = True
dati['database']['porta'] = 5433

# Salva
with open('config.json', 'w') as file:
    json.dump(dati, file, indent=2)

Validazione di file JSON

Validatori online

• JSONLint.com
• JSONFormatter.org
• Il nostro JSON Simplify

Validazione programmatica

JavaScript:

function validaJSON(testo) {
  try {
    JSON.parse(testo);
    return { valido: true };
  } catch (errore) {
    return {
      valido: false,
      messaggio: errore.message,
      posizione: errore.message.match(/position (\d+)/)?.[1]
    };
  }
}

const risultato = validaJSON('{"nome": "Mario"}');
console.log(risultato); // { valido: true }

Python:

import json

def valida_json(testo):
    try:
        json.loads(testo)
        return {"valido": True}
    except json.JSONDecodeError as e:
        return {
            "valido": False,
            "messaggio": str(e),
            "linea": e.lineno,
            "colonna": e.colno
        }

Best practices per file JSON

1. Formattazione corretta

✅ Buono:

{
  "nome": "Marco",
  "età": 30,
  "attivo": true
}

❌ Da evitare:

{"nome":"Marco","età":30,"attivo":true}

2. Denominazione coerente delle chiavi

{
  "primo_nome": "Marco",
  "cognome": "Rossi",
  "indirizzo_email": "marco@example.com"
}

3. Organizzazione logica

{
  "informazioni_base": {
    "nome": "Marco",
    "età": 30
  },
  "contatti": {
    "email": "marco@example.com",
    "telefono": "+39 123 456 7890"
  }
}

4. Gestione valori null

{
  "nome": "Marco",
  "secondo_nome": null,
  "telefono_ufficio": null
}

5. Documentazione con JSON Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Utente",
  "type": "object",
  "properties": {
    "nome": {
      "type": "string",
      "minLength": 1
    },
    "età": {
      "type": "integer",
      "minimum": 0,
      "maximum": 150
    }
  },
  "required": ["nome"]
}

Errori comuni e soluzioni

Errore 1: Virgole finali

❌ Errato:

{
  "nome": "Marco",
  "età": 30,
}

✅ Corretto:

{
  "nome": "Marco",
  "età": 30
}

Errore 2: Virgolette singole

❌ Errato:

{
  'nome': 'Marco'
}

✅ Corretto:

{
  "nome": "Marco"
}

Errore 3: Chiavi senza virgolette

❌ Errato:

{
  nome: "Marco"
}

✅ Corretto:

{
  "nome": "Marco"
}

Conclusione

I file JSON sono strumenti potenti e versatili per la memorizzazione e lo scambio di dati. Comprendere la loro struttura, sintassi e best practices ti permetterà di utilizzarli efficacemente nei tuoi progetti.

Ricorda:

• Mantieni la sintassi corretta
• Usa un'indentazione coerente
• Valida sempre i tuoi file JSON
• Segui convenzioni di denominazione chiare
• Documenta strutture complesse con JSON Schema

Con queste conoscenze, sei pronto a creare, modificare e utilizzare file JSON in modo professionale!