JSON с комментариями

JSONC (JSON with Comments) расширяет стандартный JSON, позволяя комментарии в стиле JavaScript. Многие инструменты разработки используют JSONC для файлов конфигурации, где комментарии помогают документировать настройки. Этот парсер удаляет комментарии, создавая валидный JSON, сохраняя при этом структуру данных.

Спецификации

• jsonc-parser (VS Code)
• TypeScript tsconfig.json

Типичные сценарии использования

• Разбор tsconfig.json и jsconfig.json для проектов TypeScript/JavaScript
• Чтение settings.json и конфигурации расширений VS Code
• Обработка файлов конфигурации Cloudflare wrangler.jsonc
• Редактирование конфигураций ESLint, Prettier и других инструментов со встроенной документацией

Возможности

• Разбор однострочных комментариев (// comment)
• Разбор многострочных комментариев (/* comment */)
• Обработка висящих запятых (распространены в файлах JSONC)
• Удаление комментариев для получения валидного JSON
• Все стандартные функции парсера JSON (древовидный вид, конвертация)

Примеры

{
  // Compiler options for the project
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    /* Enable all strict type checking options */
    "strict": true
  }
}

Советы

• VS Code, TypeScript и многие современные инструменты нативно поддерживают JSONC.
• При распространении конфигурации учитывайте, поддерживают ли инструменты получателей комментарии.
• Конвертируйте в стандартный JSON, удаляя комментарии, когда инструменты требуют строгий JSON.

Описание JSON с комментариями

JSONC (JSON with Comments) — это расширение стандартного JSON, которое допускает однострочные (//) и многострочные (/* */) комментарии в стиле JavaScript, а также висящие запятые после последнего элемента в массивах и объектах. Хотя это не официальный стандарт, JSONC стал де-факто форматом для файлов конфигурации, ориентированных на разработчиков, где встроенная документация повышает удобство сопровождения.

Microsoft популяризировала JSONC через Visual Studio Code, который использует его для settings.json, keybindings.json, launch.json и extensions.json. tsconfig.json TypeScript и jsconfig.json JavaScript являются файлами JSONC, как и многие конфигурации ESLint, Prettier и Babel при использовании расширения .json. wrangler.jsonc от Cloudflare явно использует расширение .jsonc для обозначения поддержки комментариев.

Ключевое преимущество JSONC перед обычным JSON — документирование. Файлы конфигурации часто содержат настройки, назначение которых неочевидно из названия ключа. Комментарии позволяют разработчикам объяснить, почему настройка существует, какие значения допустимы и каковы последствия изменений. Висящие запятые уменьшают шум в системе контроля версий, позволяя последнему элементу иметь тот же формат, что и все остальные, так что добавление нового элемента показывает только одну изменённую строку в diff вместо двух.

Под капотом парсеры JSONC работают путём удаления комментариев и висящих запятых перед передачей результата стандартному парсеру JSON. Это означает, что модель данных идентична JSON — комментарии являются метаданными для людей, а не данными для программ. При конвертации JSONC в JSON для инструментов, требующих строгого соответствия JSON, комментарии просто удаляются. Библиотека node-jsonc-parser от Microsoft, используемая в VS Code, является эталонной реализацией для разбора JSONC.

JSONC не является официальным стандартом, определённым каким-либо RFC или спецификацией ECMA. Это соглашение, популяризированное Microsoft через VS Code и TypeScript, с поведением, чётко определённым библиотекой jsonc-parser, служащей эталонной реализацией. Другие инструменты, поддерживающие JSONC — ESLint, Prettier и различные редакторы — следуют тем же соглашениям для однострочных комментариев, многострочных комментариев и висящих запятых. Распространённые файлы JSONC включают tsconfig.json и jsconfig.json (TypeScript/JavaScript), файлы настроек VS Code (settings.json, launch.json, tasks.json, keybindings.json), wrangler.jsonc (Cloudflare Workers), devcontainer.json (VS Code Dev Containers) и различные другие конфигурации инструментов. Любой JSON-файл, преимущественно редактируемый разработчиками и выигрывающий от комментариев, скорее всего, поддерживает JSONC.

JSONC следует использовать только для файлов конфигурации, читаемых инструментами с явной поддержкой JSONC. Ответы API, хранение данных и межсервисная коммуникация должны всегда использовать стандартный JSON, так как большинство парсеров JSON отклонят комментарии как синтаксические ошибки. Для программной обработки конфигурационного файла JSONC стандартным парсером JSON сначала удалите комментарии с помощью JSONC-совместимой библиотеки.

JSONC более консервативен, чем JSON5, который является более обширным надмножеством JSON. Тогда как JSONC добавляет только комментарии и висящие запятые, JSON5 также допускает строки в одинарных кавычках, ключи объектов без кавычек, шестнадцатеричные числа, начальные и конечные десятичные точки, Infinity и NaN, а также многострочные строки. JSONC имеет более широкую поддержку инструментов в экосистеме разработчиков, тогда как JSON5 используется в определённых файлах конфигурации, таких как babel.config.json5, но имеет более узкое распространение в целом.