Come validare JSON: guida completa con esempi

JSON (JavaScript Object Notation) è la pietra angolare delle moderne API web, dei file di configurazione e dello scambio di dati. Ma JSON non valido può causare crash dell'applicazione, fallimenti nell'integrazione API e ore di debug frustrante. Questa guida ti accompagnerà attraverso tutto ciò che devi sapere sulla validazione di JSON, dai controlli sintattici di base alla validazione Schema avanzata con esempi reali.

Perché la validazione JSON è importante

JSON non valido è una delle fonti più comuni di errori nelle applicazioni web. Una virgola fuori posto, una chiave senza virgolette o una virgola finale possono causare il lancio di un SyntaxError da JSON.parse(), facendo crollare l'intera pipeline di dati. La validazione cattura questi errori precocemente, prima che si propaghino nel sistema e causino guasti a valle.

Oltre alla correttezza sintattica, la validazione garantisce che i dati JSON siano conformi alla struttura prevista. Un'API potrebbe restituire JSON valido ma con campi obbligatori mancanti, tipi di dati errati o valori fuori dall'intervallo accettabile. La validazione Schema risolve questi problemi strutturali.

Regole di sintassi JSON

Prima di approfondire gli strumenti di validazione, è fondamentale comprendere le regole che rendono JSON valido. JSON ha una sintassi rigorosa definita da RFC 8259, e anche una singola violazione di un carattere può rendere l'intero documento non valido.

Le stringhe devono usare le virgolette doppie

Tutti i valori stringa e le chiavi degli oggetti devono essere racchiusi tra virgolette doppie. Le virgolette singole non sono delimitatori di stringa JSON validi, un errore comune per gli sviluppatori che provengono da JavaScript.

// Invalid - single quotes
{'name': 'Alice', 'age': 30}

// Valid - double quotes
{"name": "Alice", "age": 30}

Le chiavi degli oggetti devono essere tra virgolette

A differenza dei letterali oggetto JavaScript, JSON richiede che tutte le chiavi degli oggetti siano tra virgolette doppie. Le chiavi senza virgolette sono un errore di sintassi.

// Invalid - unquoted keys
{name: "Alice", age: 30}

// Valid - quoted keys
{"name": "Alice", "age": 30}

Nessuna virgola finale consentita

JSON non consente virgole dopo l'ultimo elemento di un oggetto o array. Questo è un altro errore comune, specialmente quando si modifica JSON manualmente.

// Invalid - trailing comma
{
  "name": "Alice",
  "age": 30,
}

// Valid - no trailing comma
{
  "name": "Alice",
  "age": 30
}

Nessun supporto per i commenti

JSON non supporta i commenti. Sia i commenti a riga singola // che i commenti multilinea /* */ non sono validi in JSON. Se hai bisogno di documentazione, usa un file separato o formati come JSONC.

Errori comuni di validazione JSON

Conoscere gli errori più comuni ti aiuta a individuarli e correggerli rapidamente. Ecco gli errori che incontrerai più spesso:

• Token imprevisto: tipicamente causato da virgolette singole, chiavi senza virgolette o virgole finali. Il messaggio di errore include la posizione dove il parsing è fallito.
• Fine imprevista dell'input JSON: la stringa JSON è incompleta o vuota. Questo accade spesso quando una richiesta di rete restituisce una risposta vuota.
• Carattere non bianco imprevisto: contenuto extra dopo il valore JSON principale, come un secondo oggetto non racchiuso in un array.
• Numero non valido: numeri con zeri iniziali (tranne 0 stesso), notazione esadecimale o valori NaN / Infinity non sono JSON validi.

Validare JSON in JavaScript

Il modo più semplice per validare JSON in JavaScript è avvolgere JSON.parse() in un blocco try-catch. Se JSON non è valido, il metodo lancia un SyntaxError.

function validateJSON(jsonString) {
  try {
    JSON.parse(jsonString);
    return { valid: true };
  } catch (error) {
    return {
      valid: false,
      error: error.message
    };
  }
}

const result = validateJSON('{"name": "Alice"}');
console.log(result);
// { valid: true }

const badResult = validateJSON("{'name': 'Alice'}");
console.log(badResult);
// { valid: false, error: "Unexpected token '..." }

Validare JSON in Python

Python fornisce il modulo json, che include json.loads() per analizzare le stringhe JSON. Similmente a JavaScript, JSON non valido solleva un json.JSONDecodeError con informazioni dettagliate sulla posizione.

import json

def validate_json(json_string):
    try:
        json.loads(json_string)
        return {"valid": True}
    except json.JSONDecodeError as e:
        return {
            "valid": False,
            "error": str(e),
            "line": e.lineno,
            "column": e.colno
        }

result = validate_json('{"name": "Alice"}')
print(result)
# {'valid': True}

Validazione JSON Schema

La validazione sintattica ti dice solo se JSON è ben formato. JSON Schema ti consente di definire la struttura prevista e validare i dati rispetto ad essa. Lo Schema specifica campi obbligatori, tipi di dati, intervalli di valori, pattern di stringhe e strutture di oggetti annidati.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["name", "email"],
  "properties": {
    "name": { "type": "string", "minLength": 1 },
    "email": { "type": "string", "format": "email" },
    "age": { "type": "integer", "minimum": 0 }
  }
}

I validatori JSON Schema più popolari includono Ajv per JavaScript, jsonschema per Python e json-schema-validator per Java. Queste librerie validano i dati JSON rispetto al tuo Schema e generano messaggi di errore dettagliati per ogni violazione.

Strumenti di validazione JSON online

Quando hai bisogno di controllare rapidamente un documento JSON senza scrivere codice, i validatori online sono l'opzione più veloce. Forniscono feedback immediato con evidenziazione degli errori e numeri di riga.

Migliori pratiche per la validazione JSON

• Valida presto: controlla JSON ai confini del sistema (come endpoint API e funzioni di importazione file), prima che i dati entrino nella logica di business.
• Usa la validazione Schema: oltre la sintassi, usa JSON Schema per validare la struttura dei dati, catturando campi mancanti, tipi errati e valori fuori intervallo.
• Fornisci messaggi di errore chiari: quando la validazione fallisce, includi il percorso del campo, il tipo previsto e il valore effettivo per aiutare gli utenti a risolvere rapidamente il problema.
• Valida sia lato client che lato server: la validazione lato client fornisce feedback immediato, mentre la validazione lato server garantisce sicurezza e integrità dei dati.
• Automatizza la validazione in CI/CD: usa strumenti come ajv-cli o jsonschema per validare fixture JSON e file di configurazione nella pipeline di build.
• Registra gli errori di validazione: registra i fallimenti di validazione con contesto per identificare pattern e correggere le cause alla radice nei produttori di dati.