От JSON5 к JSONC: более лояльный формат JSON

Когда строгий JSON заставляет вас отлаживать код глубоко за полночь из-за одной пропущенной запятой, пора познакомиться с его более лояльными собратьями — JSON5 и JSON with Comments (JSONC).

Что такое JSON5?

JSON5 — это расширение JSON, заимствующее возможности из ECMAScript 5.1: ключи без кавычек, замыкающие запятые, строки в одинарных кавычках, комментарии и шестнадцатеричные числа. Формат поддерживается сообществом и предназначен для того, чтобы конфигурационные файлы, написанные вручную, были читабельнее и прощали мелкие ошибки в большей степени, чем строгий JSON.

Что такое JSONC?

JSONC (JSON with Comments) — минимальное расширение стандартного JSON, добавляющее поддержку однострочных (//) и многострочных (/* */) комментариев, а также замыкающих запятых. Поддерживается Microsoft и используется как нативный формат настроек VS Code, файла tsconfig.json и других конфигурационных файлов TypeScript.

Зачем нужен «лояльный» JSON

Узкие места читаемости: стандартный JSON запрещает комментарии, замыкающие запятые, одинарные кавычки и так далее, что мешает ясности в конфигах и демонстрационных файлах.
Боль командной работы: гигантские JSON-файлы без подсказок поддерживать тяжело, и одно мелкое изменение может сломать всё.
Реалии DevOps: Kubernetes и CI/CD-пайплайны часто на лету объединяют или генерируют JSON; лояльный синтаксис резко сокращает ручные правки.

JSON5 и JSONC — обзор

Возможность	JSON (строгий)	JSON5	JSONC
Однострочные комментарии `//`	Нет	Да	Да
Многострочные комментарии `/* */`	Нет	Да	Да
Замыкающие запятые	Нет	Да	Да
Строки в одинарных кавычках	Нет	Да	Нет
Ключи без кавычек	Нет	Да	Нет
Числовые знаки `+` / `-`	Нет	Да	Нет
Hex- / двоичные числа	Нет	Да	Нет
Кто поддерживает спецификацию	ECMA	Сообщество (А. Раушмайер)	Microsoft / VS Code

Одной фразой: JSON5 ощущается как литерал JavaScript-объекта, а JSONC — это просто стандартный JSON плюс комментарии.

Примеры синтаксиса

Чистый JSON (строгий)

{
  "name": "Go Tools",
  "features": ["Base64", "JSON Formatter"]
}

Пример JSON5

// Конфиг проекта
{
  name: 'Go Tools',      // одинарные кавычки и ключи без кавычек
  features: [
    'Base64',
    'JSON Formatter',    // замыкающая запятая
  ],
  version: 1.0,          // допустимо число без строки
}

Пример JSONC

{
  // Имя проекта
  "name": "Go Tools",
  // Список возможностей
  "features": [
    "Base64",
    "JSON Formatter", // замыкающая запятая
  ]
}

Поддержка форматирования и разбора

Сценарий	JSON5	JSONC	Рекомендуемые библиотеки и инструменты
Браузер	Полифилл `JSON5.parse()`, Prettier со встроенным парсером `json5` (≥ v1.13)	Нативная поддержка `settings.json` в VS Code	—
Node.js	npm-пакет `json5`	`comment-json`, `jsonc-parser`	Поддерживают форматирование из CLI и разбор AST
IDE	Расширения для VS Code, WebStorm	Нативно в VS Code, плагин для WebStorm	Prettier унифицирует форматирование
CI / Lint	`eslint-plugin-json5`	`eslint-plugin-jsonc`	Интеграция с Husky и lint-staged
Онлайн-инструмент	JSON Formatter Go Tools (форматирует и валидирует JSON5/JSONC)	То же	JSON Formatter

Быстрое форматирование в VS Code

Добавьте в settings.json:

"[jsonc]": {
  "editor.defaultFormatter": "esbenp.prettier-vscode"
}

Затем нажмите Alt + Shift + F, чтобы отформатировать любой JSONC-файл.

Реальные конфигурационные файлы

JSON5 и JSONC уже широко используются в конфигурационных файлах, с которыми вы сталкиваетесь ежедневно. Ниже — конкретные примеры:

TypeScript (tsconfig.json — JSONC)

{
  // Строгий режим ловит больше ошибок на этапе компиляции
  "compilerOptions": {
    "strict": true,
    "target": "ES2022",
    "module": "ESNext",
    "outDir": "./dist",
    // Алиасы путей делают импорты чище
    "paths": {
      "@/*": ["./src/*"],
      "@tests/*": ["./tests/*"],
    },
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"],
}

tsconfig.json в TypeScript нативно использует JSONC — комментарии и замыкающие запятые работают «из коробки». Это один из самых распространённых JSONC-файлов в любом JavaScript- или TypeScript-проекте.

Flat-конфиг ESLint (eslint.config.json — JSONC)

{
  "rules": {
    // Предупреждать на console.log, но разрешать console.error
    "no-console": ["warn", { "allow": ["error", "warn"] }],
    "semi": ["error", "always"],
    "quotes": ["error", "double"],
  }
}

Babel (babel.config.json5 — JSON5)

{
  // Одинарные кавычки и ключи без кавычек делают конфиг читабельнее
  presets: [
    ['@babel/preset-env', {
      targets: '> 0.25%, not dead',
      modules: false,  // Отдадим модули сборщику
    }],
  ],
  plugins: [
    '@babel/plugin-transform-runtime',
  ],
}

Настройки рабочей области VS Code (.vscode/settings.json — JSONC)

{
  // Настройки редактора
  "editor.fontSize": 14,
  "editor.tabSize": 2,
  "editor.formatOnSave": true,

  // Переопределения по языку
  "[typescript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode",
  },
  "[jsonc]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode",
  },
}

Практические советы и оговорки

1. Конвертируйте перед продакшеном

Браузеры по-прежнему требуют строгий JSON для JSON.parse. Используйте билд-инструменты, чтобы убрать комментарии и замыкающие запятые:

// Build-скрипт на Node.js: конвертирует JSON5-конфиг в строгий JSON
import JSON5 from 'json5';
import { readFileSync, writeFileSync } from 'fs';

const config = JSON5.parse(readFileSync('config.json5', 'utf8'));
writeFileSync('config.json', JSON.stringify(config, null, 2));

Для бандлеров используйте rollup-plugin-json5 или vite-plugin-json5, чтобы конвертация выполнялась автоматически во время сборки.

2. Безопасность и надёжность

Лояльность может скрывать «лишние» поля. Всегда валидируйте конфигурацию через JSON Schema или zod, прежде чем её применять. И при работе со snapshot-тестами помните: разница JSON5 / JSONC между запусками часто «шумит» на полях вроде timestamp, requestId и UUID — практические паттерны игнорирования таких полей разобраны в гайде по игнорированию timestamp и ID при JSON diff. Если в проекте параллельно лежат YAML-конфиги, особенно для Kubernetes — обратите внимание на «норвежскую проблему» YAML и различия JSON-YAML: безкавычные значения вроде no и off тихо превращаются в boolean.

// Проверяем форму конфига через zod после разбора
import { z } from 'zod';
import JSON5 from 'json5';

const ConfigSchema = z.object({
  port: z.number().min(1).max(65535),
  host: z.string(),
  debug: z.boolean().default(false),
});

const raw = JSON5.parse(readFileSync('config.json5', 'utf8'));
const config = ConfigSchema.parse(raw); // Бросит ошибку при несоответствии

3. Командные соглашения

В README объявите, что *.json5 — только для конфигов; пакеты для релиза должны поставляться со строгим .json.
Стандартизируйте правила Prettier, чтобы избежать «шумных» диффов.
Используйте .editorconfig для согласованных отступов в JSON, JSON5 и JSONC.

4. Производительность

Разбор JSON5/JSONC добавляет зависимости и небольшой оверхед — приемлемо для CLI и dev-инструментов, но в продакшене всё нужно измерять. Пакет json5 в npm весит около 8 КБ в минифицированном виде, разбор примерно в 2–5 раз медленнее нативного JSON.parse. Для конфигурационных файлов, загружаемых один раз при старте, это незаметно. На горячих путях, где разбираются тысячи объектов в секунду, придерживайтесь строгого JSON.

Часто задаваемые вопросы

В чём разница между JSON5 и JSONC?

JSON5 расширяет JSON синтаксисом, похожим на JavaScript: ключи без кавычек, замыкающие запятые, однострочные и блочные комментарии, hex-числа и многострочные строки. JSONC проще — он добавляет к стандартному JSON только однострочные (//) и блочные (/* */) комментарии. Выбирайте JSONC для конфигов, где достаточно комментариев, и JSON5, когда нужен более богатый синтаксис.

Можно ли использовать JSON5 или JSONC в продакшен-API?

Нет — JSON5 и JSONC спроектированы для конфигурационных файлов, а не для обмена данными. В API следует использовать стандартный JSON (RFC 8259) для максимальной совместимости. Оставьте JSON5/JSONC для локальных конфигов вроде tsconfig.json, .vscode/settings.json или конфигурации окружения, где читаемость для человека важнее, чем удобство машины.

VS Code поддерживает JSON5 нативно?

VS Code поддерживает JSONC нативно (его собственные файлы настроек используют JSONC), но не поддерживает JSON5 «из коробки». Для JSON5 установите специализированное расширение, например «JSON5 syntax» из маркетплейса VS Code. В настройках также можно ассоциировать файлы .json5 с языковым режимом JSON5.

Как конвертировать JSON5 в стандартный JSON?

Используйте npm-пакет json5: JSON5.parse() читает JSON5, затем JSON.stringify() выводит стандартный JSON. Для CLI: npx json5 < input.json5 > output.json. Онлайн-инструменты, например наш JSON Formatter, помогут проверить корректность результата.

JSONC — это то же самое, что «JSON with Comments»?

Да — JSONC расшифровывается как «JSON with Comments» и используется в VS Code, TypeScript (tsconfig.json) и других инструментах Microsoft. Формат следует стандартной спецификации JSON и добавляет только комментарии // и /* */. Парсеры удаляют комментарии до обработки, поэтому итоговая структура данных идентична стандартному JSON.

Подборка браузерных инструментов разработчика, включая кодирование Base64, генерацию хешей и конвертацию timestamp, разобрана в подборке базовых инструментов разработчика.

Итог

Поиск баланса между читаемостью и строгостью — классическая дилемма разработчика. JSON5 и JSONC улучшают опыт написания, и при правильно настроенном пайплайне сборки и валидации можно безопасно пользоваться преимуществами «лояльного JSON».

От JSON5 к JSONC: руководство по более лояльному формату JSON