ENRU

Комментарии в 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, файл .jsonComments 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 jsonExpecting property name enclosed in double quotes: line 2 column 3 (char 4). Перевод: «ожидалось имя свойства в двойных кавычках: строка 2, столбец 3 (символ 4)».
Go encoding/jsoninvalid character '/' looking for beginning of object key string. Перевод: «недопустимый символ „/“ там, где должна начаться строка ключа».
JacksonUnexpected character ('/' (code 47)): maybe a (non-standard) comment? (not recognized as one since Feature 'ALLOW_COMMENTS' not enabled for parser). Перевод: «неожиданный символ „/“: может быть, (нестандартный) комментарий? Не распознан, потому что настройка ALLOW_COMMENTS выключена».
jqjq: 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 имеет смысл, только если программа, которая читает файл, тоже понимает комментарии.