Czy JSON może mieć komentarze
Podsumowanie: RFC 8259 nie ma składni komentarzy, więc // i komentarze blokowe powodują błąd JSON.parse. Zamiast tego użyj JSON5 lub JSONC, pola _comment, description w Schema albo YAML.
Najważniejsze: nigdy nie umieszczaj komentarzy w standardowym JSON-ie; używaj JSONC lub JSON5 do lokalnej konfiguracji edytowanej wyłącznie przez ludzi, przenieś wyjaśnienia do description w JSON Schema, gdy plik przekracza granice systemów, i przejdź na YAML lub TOML, gdy wolumen adnotacji rośnie.
Nie.
Każdy parser zgodny ze standardem odrzuca to:
{
"port": 8080 // local development only
}
Chrome zgłasza SyntaxError: Unexpected token }. Parser trafił na /, który nie może rozpocząć żadnej wartości JSON, i zatrzymał się.
Dlaczego specyfikacja celowo pomija komentarze
RFC 8259 definiuje sześć wartości: obiekt, tablicę, liczbę, łańcuch, true/false, null. Nie ma produkcji komentarza.
Komentarze zaproponowano wcześnie i odrzucono z konkretnego powodu: gdy komentarze stają się legalne, ktoś używa ich do przenoszenia dyrektyw — warunkowych dołączeń, zmiennych szablonów — i każdy parser wyrasta we własny dialekt. Interoperacyjność pęka przy pierwszym skoku. JSON jest celowo wyłącznie danymi, bez niczego wykonywalnego w środku.
Cztery sposoby na zachowanie uwag
1. Użyj nadzbioru. JSON5 i JSONC akceptują oba style komentarzy. settings.json i tsconfig.json w VS Code to JSONC.
Koszt jest realny: JSON.parse nadal je odrzuca, a API, potoki logów i kolejki komunikatów zwykle akceptują tylko standardowy JSON. Twój komentarz zostaje po cichu odrzucony albo rzuca gdzieś niżej.
2. Umieść uwagę w danych.
{
"_comment": "port assigned by ops, do not change",
"port": 8080
}
Działa wszędzie, ale zanieczyszcza model: każdy konsument musi wiedzieć, które klucze ignorować, a definicja typu zyskuje pole, które nie jest naprawdę danymi.
3. Użyj description w Schema. description jest przeznaczone dla ludzi i narzędzi. Walidatory je ujawniają, edytory pokazują po najechaniu, a nigdy nie trafia do ładunku. To jedyna opcja, która przetrwa długoterminowe utrzymanie bez łamania zgodności.
4. Zmień format pliku. Jeśli plik istnieje po to, by być edytowany ręcznie, YAML lub TOML wspierają komentarze natywnie. Walka z JSON-em tutaj to zmarnowany wysiłek.
Wybór
| Sytuacja | Odpowiedź |
|---|---|
| Wysyłane do innego systemu przez API lub kolejkę | Bez komentarzy; dokumentuj w Schema lub dokumentacji zewnętrznej |
| Konfiguracja czytana wyłącznie przez ludzi i edytory | JSONC, z rozszerzeniem .jsonc |
| Potrzebne uniwersalne narzędzia i wyjaśnienie inline | Standardowy JSON plus description w Schema |
| Długa konfiguracja z dużą ilością adnotacji | Przejdź na YAML |
FAQ
Dlaczego pole _comment zanieczyszcza model?
Bo staje się częścią danych. Każdy konsument musi wiedzieć, które klucze ignorować, a definicja typu zyskuje pole, które nie jest naprawdę danymi biznesowymi.
Czy wyjaśnienie powinno żyć w description JSON Schema?
Tak. description zostaje poza ładunkiem, a walidatory je ujawniają i edytory pokazują po najechaniu, więc to jedyna opcja, która przetrwa długoterminowe utrzymanie bez łamania zgodności.
Czy JSONC lub JSON5 da się sparsować przez JSON.parse?
Nie. JSON.parse nadal odrzuca komentarze, a API, potoki logów i kolejki komunikatów zwykle akceptują tylko standardowy JSON, więc komentarz zostaje odrzucony albo rzuca gdzieś niżej.
Narzędzia
- Parser JSON5 — wklej konfigurację z komentarzami i zobacz rozwiązana strukturę
- Formater i walidator JSON — nielegalny JSON jest zgłaszany z wierszem i kolumną, więc naruszający komentarz jest oczywisty