Může JSON obsahovat komentáře
Shrnutí: RFC 8259 nemá syntaxi pro komentáře, takže `//` a blokové komentáře způsobí, že `JSON.parse` vyhodí chybu. Použijte JSON5 nebo JSONC, pole `_comment`, `description` ve Schema, nebo YAML.
Stručně: nikdy nedávejte komentáře do standardního JSON; pro lokální konfiguraci, kterou upravují jen lidé, použijte JSONC nebo JSON5, vysvětlivky přesuňte do description v JSON Schema, když soubor překračuje systémy, a přejděte k YAML nebo TOML, jakmile objem poznámek vzroste.
Ne.
Jakýkoli parser odpovídající standardu to odmítne:
{
"port": 8080 // jen pro lokální vývoj
}
Chrome hlásí SyntaxError: Unexpected token }. Parser narazil na /, který nemůže začínat žádnou hodnotu JSON, a skončil.
Proč specifikace komentáře záměrně vynechává
RFC 8259 definuje šest hodnot: objekt, pole, číslo, řetězec, true/false, null. Žádná produkce pro komentáře neexistuje.
Komentáře byly navrženy brzy a odmítnuty z konkrétního důvodu: jakmile jsou komentáře legální, někdo je začne používat k nesení direktiv – podmíněných include, šablonovacích proměnných – a každý parser si vypěstuje vlastní dialekt. Interoperabilita se rozbije hned na prvním skoku. JSON je záměrně jen data, uvnitř není nic vykonavatelného.
Čtyři způsoby, jak si poznámky udržet
1. Použijte nadmnožinu. JSON5 i JSONC přijímají oba styly komentářů. settings.json a tsconfig.json ve VS Code jsou JSONC.
Cena je skutečná: JSON.parse je stále odmítá a API, logovací pipeline i fronty zpráv obvykle přijímají jen standardní JSON. Váš komentář se tiše zahodí, nebo někde níž vyhodí chybu.
2. Dejte poznámku do dat.
{
"_comment": "port přidělilo ops, neměnit",
"port": 8080
}
Funguje všude, ale znečišťuje model: každý konzument musí vědět, které klíče ignorovat, a vaše definice typu získá pole, které ve skutečnosti není data.
3. Použijte description ve Schema. description je určen pro lidi a nástroje. Validátory ho vystavují, editory ho zobrazují při najetí myší a nikdy nevstoupí do payloadu. Je to jediná možnost, která přežije dlouhodobou údržbu, aniž by rozbila kompatibilitu.
4. Změňte formát souboru. Pokud soubor existuje, aby ho lidé upravovali ručně, YAML nebo TOML komentáře podporují nativně. Bojovat tady s JSON je zbytečné úsilí.
Volba
| Situace | Odpověď |
|---|---|
| Odesílá se do jiného systému, přes API nebo frontu | Žádné komentáře; dokumentujte ve Schema nebo externí dokumentaci |
| Konfiguraci čtou jen lidé a editory | JSONC, s příponou .jsonc |
| Potřebuje univerzální nástroje a inline vysvětlení | Standardní JSON plus description ve Schema |
| Dlouhá konfigurace se spoustou poznámek | Přejděte k YAML |
Časté dotazy
Proč pole _comment znečišťuje model?
Protože se stane součástí dat. Každý konzument musí vědět, které klíče ignorovat, a definice typu získá pole, které ve skutečnosti není obchodní data.
Má vysvětlení žít v description v JSON Schema?
Ano. description zůstává mimo payload, zatímco validátory ho vystavují a editory ho zobrazují při najetí myší, takže je to jediná možnost, která přežije dlouhodobou údržbu, aniž by rozbila kompatibilitu.
Může JSONC nebo JSON5 parsovat JSON.parse?
Ne. JSON.parse komentáře stále odmítá a API, logovací pipeline i fronty zpráv obvykle přijímají jen standardní JSON, takže komentář se zahodí, nebo někde níž vyhodí chybu.
Nástroje
- Parser JSON5 — vložte konfiguraci s komentáři a podívejte se na vyřešenou strukturu
- Formátovač a validátor JSON — neplatný JSON se hlásí s řádkem a sloupcem, takže problematický komentář je zřejmý