JSON può avere commenti
In sintesi: RFC 8259 non ha sintassi per i commenti, quindi // e i commenti a blocco fanno lanciare un errore a JSON.parse. Usa invece JSON5 o JSONC, un campo _comment, una description di Schema o YAML.
In sintesi: non inserire mai commenti nel JSON standard; usa JSONC o JSON5 per la configurazione locale che solo gli umani modificano, sposta le spiegazioni in una description di JSON Schema quando il file attraversa sistemi, e passa a YAML o TOML quando il volume delle annotazioni cresce.
No.
Qualsiasi parser conforme allo standard rifiuta questo:
{
"port": 8080 // local development only
}
Chrome riporta SyntaxError: Unexpected token }. Il parser ha incontrato /, che non può iniziare alcun valore JSON, e si è fermato.
Perché la specifica omette intenzionalmente i commenti
RFC 8259 definisce sei valori: oggetto, array, numero, stringa, true/false, null. Non esiste alcuna produzione per i commenti.
I commenti furono proposti presto e respinti per una ragione concreta: una volta che i commenti sono legali, qualcuno li usa per veicolare direttive — inclusioni condizionali, variabili di template — e ogni parser sviluppa il proprio dialetto. L'interoperabilità si rompe al primo passaggio. JSON è deliberatamente solo dati, senza nulla di eseguibile al suo interno.
Quattro modi per conservare le tue note
1. Usa un superset. JSON5 e JSONC accettano entrambi gli stili di commento. Il settings.json e il tsconfig.json di VS Code sono JSONC.
Il costo è reale: JSON.parse continua a rifiutarli, e API, pipeline di log e code di messaggi di solito accettano solo JSON standard. Il tuo commento viene eliminato silenziosamente o lancia un errore da qualche parte a valle.
2. Metti la nota nei dati.
{
"_comment": "port assigned by ops, do not change",
"port": 8080
}
Funziona ovunque, ma inquina il modello: ogni consumatore deve sapere quali chiavi ignorare, e la tua definizione di tipo guadagna un campo che non è davvero un dato.
3. Usa una description di Schema. description è pensata per umani e strumenti. I validatori la mostrano, gli editor la visualizzano al passaggio del mouse, e non entra mai nel payload. È l'unica opzione che sopravvive alla manutenzione a lungo termine senza rompere la compatibilità.
4. Cambia il formato del file. Se il file esiste per essere modificato a mano, YAML o TOML supportano nativamente i commenti. Combattere con JSON qui è fatica sprecata.
Scegliere
| Situazione | Risposta |
|---|---|
| Inviato a un altro sistema, tramite un'API o una coda | Niente commenti; documenta nello Schema o in documentazione esterna |
| Configurazione letta solo da umani ed editor | JSONC, con estensione .jsonc |
| Necessita di strumenti universali e spiegazioni inline | JSON standard più description di Schema |
| Configurazione lunga con molte annotazioni | Passa a YAML |
FAQ
Perché un campo _comment inquina il modello?
Perché diventa parte dei dati. Ogni consumatore deve sapere quali chiavi ignorare, e la definizione di tipo guadagna un campo che non è davvero un dato di business.
La spiegazione dovrebbe stare in una description di JSON Schema?
Sì. description resta fuori dal payload, mentre i validatori la mostrano e gli editor la visualizzano al passaggio del mouse, quindi è l'unica opzione che sopravvive alla manutenzione a lungo termine senza rompere la compatibilità.
JSONC o JSON5 possono essere analizzati da JSON.parse?
No. JSON.parse rifiuta ancora i commenti, e API, pipeline di log e code di messaggi di solito accettano solo JSON standard, quindi il commento viene eliminato o lancia un errore da qualche parte a valle.
Strumenti
- Parser JSON5 — incolla una configurazione con commenti e vedi la struttura risolta
- Formattatore e validatore JSON — il JSON illegale viene riportato con riga e colonna, quindi il commento incriminato è evidente