Комментарии в JSON: можно ли, JSONC, JSON5 и обходные пути
Обновлено
Нельзя. В стандартном JSON нет комментариев: ни //, ни /* */, ни #. Строгие парсеры их отвергают, а Visual Studio Code (VS Code) подчёркивает их с сообщением «Comments are not permitted in JSON.» (перевод: «комментарии в JSON не допускаются»). Ниже — почему в формате их нет, что говорят парсеры, встретив комментарий, какие два формата их разрешают, JSONC и JSON5, и как оставить пометку или убрать комментарии, ничего не сломав.
Почему в JSON нет комментариев
RFC 8259 разрешает между токенами четыре пробельных символа: пробел, табуляцию, перевод строки и возврат каретки. Ничего другого вне строк быть не может, поэтому / — просто неожиданный символ. Дуглас Крокфорд, автор спецификации JSON, объяснял, что убрал комментарии намеренно: в них начали передавать директивы для парсера, а это разрушило бы совместимость. Для конфигов с пояснениями он советовал писать комментарии и вырезать их до того, как файл попадёт в JSON-парсер.
Раздел 9 RFC позволяет парсеру принимать «не-JSON формы или расширения», поэтому некоторые так и делают. Но файл с комментариями — уже не JSON, и следующий инструмент в цепочке вправе его отвергнуть.
{
// порт для локальной разработки
"port": 8080
}Что парсеры говорят об этом комментарии
Те же четыре строки в строгих парсерах. Каждый останавливается на /:
| Где | Сообщение |
|---|---|
VS Code, файл .json | Comments are not permitted in JSON. (код 521). Перевод: «комментарии в JSON не допускаются». |
| Chrome, Node.js (V8) | Expected property name or '}' in JSON at position 4 (line 2 column 3). Перевод: «ожидалось имя свойства или „}“ в позиции 4 (строка 2, столбец 3)». |
Python json | Expecting property name enclosed in double quotes: line 2 column 3 (char 4). Перевод: «ожидалось имя свойства в двойных кавычках: строка 2, столбец 3 (символ 4)». |
Go encoding/json | invalid character '/' looking for beginning of object key string. Перевод: «недопустимый символ „/“ там, где должна начаться строка ключа». |
| Jackson | Unexpected character ('/' (code 47)): maybe a (non-standard) comment? (not recognized as one since Feature 'ALLOW_COMMENTS' not enabled for parser). Перевод: «неожиданный символ „/“: может быть, (нестандартный) комментарий? Не распознан, потому что настройка ALLOW_COMMENTS выключена». |
| jq | jq: parse error: Invalid numeric literal at line 2, column 5. Перевод: «ошибка разбора: недопустимый числовой литерал в строке 2, столбце 5». |
Проверено на Node.js 25.1, Python 3.9, Go 1.25, Jackson 2.15 и jq 1.7.1; текст VS Code взят из его языкового сервиса JSON. Комментарий в другом месте даёт другие сообщения: все они с исправлениями собраны на странице об ошибке комментария.
JSONC: JSON с комментариями
JSONC — это JSON плюс комментарии // и /* */. Формальной спецификации у него нет; на практике это то, что принимает jsonc-parser от Microsoft, на котором построена поддержка JSON в VS Code. Редактор открывает settings.json, launch.json, tasks.json, keybindings.json, devcontainer.json, tsconfig.json, .eslintrc.json и любой файл .jsonc в режиме JSON with Comments. Там комментарии допустимы, а висячая запятая получает предупреждение «Trailing comma» (код 519), если схема файла её не разрешает; схема tsconfig разрешает. В обычном файле .json и то и другое — ошибки.
Когда VS Code ругается на комментарий, сначала стоит понять, что это за файл:
- Данные или файл, который читает строгий парсер, например
package.jsonили тело запроса к API: комментарий убрать. Ни npm, ниJSON.parseего не примут. - Конфиг программы, которая понимает комментарии: переключить режим языка на «JSON with Comments» в строке состояния или привязать файл в настройках через
files.associations. - Непонятно: заглянуть в документацию программы. Режим редактора меняет только подчёркивания, а не то, что программа примет при запуске.
{
"files.associations": {
"app.config.json": "jsonc"
}
}JSON5
JSON5 идёт дальше. Кроме комментариев он разрешает висячие запятые, строки в одинарных кавычках, ключи без кавычек, шестнадцатеричные числа, точку в начале и в конце числа, Infinity и NaN, а ещё строки, разбитые на несколько строк. Любой документ JSON — валидный JSON5, так что парсер JSON5 читает и обычный JSON.
import JSON5 from 'json5';
JSON5.parse(`{
// порт для локальной разработки
port: 8080,
hosts: ['localhost', '127.0.0.1',],
}`);
// { port: 8080, hosts: [ 'localhost', '127.0.0.1' ] }Чтобы получить из JSON5 обычный JSON, достаточно разобрать его и сериализовать результат: JSON.stringify(JSON5.parse(text), null, 2). Две оговорки: комментарии после этого пропадут, а пакет json5 читает числа как double, так что 12345678901234567890 превращается в 12345678901234567000 — та же проблема больших чисел, что и у JSON.parse. В Python есть пакет json5 с той же идеей, а Jackson читает комментарии, если включить JsonReadFeature.ALLOW_JAVA_COMMENTS.
Как оставить пометку в обычном JSON
- Поле-комментарий:
"_comment": "…"или"//": "…". Его примет любой парсер, но это данные: их видит каждый потребитель, схема сadditionalProperties: falseтакое поле отвергнет, а второй"//"в том же объекте — повторный ключ, и большинство парсеров оставят только последний. - Схема:
descriptionу каждого поля в JSON Schema файла (редакторы показывают его при наведении) или ключевое слово$commentдля заметок внутри самой схемы. - Исходник с комментариями: хранить в репозитории
config.jsoncи собирать из негоconfig.jsonпри сборке. - Формат для людей: если файл правят руками и комментарии важны, в YAML они есть изначально. Подробнее — JSON или YAML и JSON в YAML.
{
"_comment": "порт для локальной разработки",
"port": 8080
}Как убрать комментарии перед разбором
Если исходник должен хранить комментарии, а читатель строгий, комментарии вырезают при сборке или при загрузке. Для этого нужен токенизатор вроде strip-json-comments или jsonc-parser, а не регулярное выражение: в "https://example.com" есть // внутри строки, и наивный шаблон разрежет её пополам.
import stripJsonComments from 'strip-json-comments';
import { parse } from 'jsonc-parser';
const text = '{\n // порт для локальной разработки\n "url": "https://example.com", /* хост */\n "port": 8080\n}';
JSON.parse(stripJsonComments(text)); // { url: 'https://example.com', port: 8080 }
parse(text); // то же: jsonc-parser пропускает комментарииВ Go то же делает пакет hujson от Tailscale: hujson.Standardize превращает JSON с комментариями и висячими запятыми в обычный JSON. В Python такие файлы сразу читает json5.loads.
Валидатор здесь строгий: комментарий — это ошибка со своим кодом, строкой и столбцом, и ничего не вырезается втихую. С висячей запятой обращение такое же.
Комментарии в JSON: частые вопросы
Поддерживает ли JSON комментарии?
Нет. В RFC 8259 нет синтаксиса комментариев, и JSON.parse, модуль json в Python, encoding/json в Go и Jackson с настройками по умолчанию отвергают // и /* */. JSONC и JSON5 — отдельные форматы, где они разрешены.
Как закомментировать строку в JSON?
Никак. Строку можно удалить, спрятать значение под ключ, который никто не читает (переименовать "port" в "_port"), или держать файл в JSONC и вырезать комментарии перед разбором. Осторожно с запятыми: если убрать последний элемент, останется висячая запятая.
Чем JSONC отличается от JSON5?
JSONC — это JSON плюс комментарии, а висячие запятые терпят лишь некоторые инструменты. JSON5 вдобавок разрешает ключи без кавычек, одинарные кавычки, шестнадцатеричные числа, Infinity и NaN. Обоим нужен свой парсер.
Почему VS Code разрешает комментарии в settings.json, но не в моём файле?
Он открывает settings.json как «JSON with Comments», а остальные файлы .json — как строгий JSON. Менять режим или прописывать files.associations имеет смысл, только если программа, которая читает файл, тоже понимает комментарии.