Чи може JSON мати коментарі
Головне: У RFC 8259 немає синтаксису коментарів, тож `//` і блокові коментарі змушують JSON.parse кидати виняток. Натомість використовуйте JSON5 або JSONC, поле `_comment`, опис Schema чи YAML.
Коротко: ніколи не кладіть коментарі в стандартний JSON; використовуйте JSONC або JSON5 для локальної конфігурації, яку редагують лише люди, переносьте пояснення в description JSON Schema, коли файл перетинає системи, і переходьте на YAML чи TOML, коли обсяг анотацій зростає.
Ні.
Будь-який парсер, що відповідає стандарту, відхиляє це:
{
"port": 8080 // local development only
}
Chrome повідомляє SyntaxError: Unexpected token }. Парсер натрапив на /, що не може починати жодне значення JSON, і зупинився.
Чому специфікація навмисно лишає коментарі поза межами
RFC 8259 визначає шість значень: обʼєкт, масив, число, рядок, true/false, null. Продукції коментаря немає.
Коментарі пропонували рано й відхилили з конкретної причини: щойно коментарі стають законними, хтось починає використовувати їх для директив — умовних включень, змінних шаблонів — і кожен парсер вирощує власний діалект. Сумісність ламається на першому переході. JSON навмисно є лише даними, нічого виконуваного всередині.
Чотири способи зберегти примітки
1. Використовуйте надмножину. JSON5 і JSONC приймають обидва стилі коментарів. settings.json і tsconfig.json у VS Code — це JSONC.
Ціна реальна: JSON.parse усе одно їх відхиляє, а API, конвеєри логів і черги повідомлень зазвичай приймають лише стандартний JSON. Ваш коментар мовчки відкидається або кидає виняток десь нижче за течією.
2. Покладіть примітку в дані.
{
"_comment": "port assigned by ops, do not change",
"port": 8080
}
Працює всюди, але забруднює модель: кожен споживач має знати, які ключі ігнорувати, а ваше визначення типу отримує поле, що не є справжніми даними.
3. Використайте опис Schema. description призначений для людей і інструментів. Валідатори його показують, редактори показують при наведенні, і він ніколи не потрапляє в навантаження. Це єдиний варіант, що виживає в довготривалій підтримці, не ламаючи сумісності.
4. Змініть формат файлу. Якщо файл існує, щоб його редагували вручну, YAML або TOML рідно підтримують коментарі. Боротьба з JSON тут — марна праця.
Вибір
| Ситуація | Відповідь |
|---|---|
| Надсилається в іншу систему, через API чи чергу | Без коментарів; документуйте в Schema або зовнішній документації |
| Конфігурація, що читають лише люди й редактори | JSONC, із розширенням .jsonc |
| Потрібен універсальний інструментарій і вбудоване пояснення | Стандартний JSON плюс description Schema |
| Довга конфігурація з великою кількістю анотацій | Перейдіть на YAML |
Часті питання
Чому поле _comment забруднює модель?
Бо воно стає частиною даних. Кожен споживач має знати, які ключі ігнорувати, а визначення типу отримує поле, що не є справжніми бізнес-даними.
Чи має пояснення жити в описі JSON Schema?
Так. description залишається поза навантаженням, тоді як валідатори його показують, а редактори — при наведенні, тож це єдиний варіант, що виживає в довготривалій підтримці, не ламаючи сумісності.
Чи може JSON.parse розібрати JSONC або JSON5?
Ні. JSON.parse усе одно відхиляє коментарі, а API, конвеєри логів і черги повідомлень зазвичай приймають лише стандартний JSON, тож коментар відкидається або кидає виняток десь нижче за течією.
Інструменти
- Парсер JSON5 — вставте конфігурацію з коментарями й побачте розвʼязану структуру
- Форматувальник і валідатор JSON — недопустимий JSON повідомляється з рядком і стовпцем, тож проблемний коментар очевидний