Может ли 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 остаётся вне полезной нагрузки, при этом валидаторы его показывают, а редакторы показывают при наведении, поэтому это единственный вариант, который выживает при долгосрочном сопровождении без нарушения совместимости.
Могут ли JSONC или JSON5 разбираться через JSON.parse?
Нет. JSON.parse всё равно отвергает комментарии, а API, конвейеры логов и очереди сообщений обычно принимают только стандартный JSON, поэтому комментарий отбрасывается или падает где-то ниже.
Инструменты
- Парсер JSON5 — вставьте конфигурацию с комментариями и посмотрите разрешённую структуру
- Форматтер и валидатор JSON — нелегальный JSON сообщается со строкой и столбцом, так что проблемный комментарий очевиден