# Комментарии в JSON: можно ли, JSONC, JSON5 и обходные пути

> Узнать, можно ли писать комментарии в JSON, что значит «Comments are not permitted in JSON» в VS Code и когда брать JSONC или JSON5 вместо обычного JSON.

- Адрес: https://jsonstatham.dev/ru/guides/json-comments/
- Язык: Русский (ru)
- Английская версия: https://jsonstatham.dev/guides/json-comments.md
- Обновлено: 2026-11-08

Нельзя. В стандартном JSON нет комментариев: ни `//`, ни `/* */`, ни `#`. Строгие парсеры их отвергают, а Visual Studio Code (VS Code) подчёркивает их с сообщением «Comments are not permitted in JSON.» (перевод: «комментарии в JSON не допускаются»). Ниже — почему в формате их нет, что говорят парсеры, встретив комментарий, какие два формата их разрешают, JSONC и JSON5, и как оставить пометку или убрать комментарии, ничего не сломав.

## Почему в JSON нет комментариев

[RFC 8259](https://www.rfc-editor.org/rfc/rfc8259#section-2) разрешает между токенами четыре пробельных символа: пробел, табуляцию, перевод строки и возврат каретки. Ничего другого вне строк быть не может, поэтому `/` — просто неожиданный символ. Дуглас Крокфорд, автор спецификации JSON, объяснял, что убрал комментарии намеренно: в них начали передавать директивы для парсера, а это разрушило бы совместимость. Для конфигов с пояснениями он советовал писать комментарии и вырезать их до того, как файл попадёт в JSON-парсер.

[Раздел 9](https://www.rfc-editor.org/rfc/rfc8259#section-9) RFC позволяет парсеру принимать «не-JSON формы или расширения», поэтому некоторые так и делают. Но файл с комментариями — уже не 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. Комментарий в другом месте даёт другие сообщения: все они с исправлениями собраны на [странице об ошибке комментария](https://jsonstatham.dev/ru/errors/comments/).

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

JSONC — это JSON плюс комментарии `//` и `/* */`. Формальной спецификации у него нет; на практике это то, что принимает [jsonc-parser](https://github.com/microsoft/node-jsonc-parser) от Microsoft, на котором построена поддержка JSON в VS Code. Редактор открывает `settings.json`, `launch.json`, `tasks.json`, `keybindings.json`, `devcontainer.json`, `tsconfig.json`, `.eslintrc.json` и любой файл `.jsonc` в режиме [JSON with Comments](https://code.visualstudio.com/docs/languages/json#_json-with-comments). Там комментарии допустимы, а висячая запятая получает предупреждение «Trailing comma» (код 519), если схема файла её не разрешает; схема tsconfig разрешает. В обычном файле `.json` и то и другое — ошибки.

Когда VS Code ругается на комментарий, сначала стоит понять, что это за файл:

- **Данные или файл, который читает строгий парсер,** например `package.json` или тело запроса к API: комментарий убрать. Ни npm, ни `JSON.parse` его не примут.
- **Конфиг программы, которая понимает комментарии:** переключить режим языка на «JSON with Comments» в строке состояния или привязать файл в настройках через `files.associations`.
- **Непонятно:** заглянуть в документацию программы. Режим редактора меняет только подчёркивания, а не то, что программа примет при запуске.

```json
{
  "files.associations": {
    "app.config.json": "jsonc"
  }
}
```

## JSON5

[JSON5](https://json5.org/) идёт дальше. Кроме комментариев он разрешает висячие запятые, строки в одинарных кавычках, ключи без кавычек, шестнадцатеричные числа, точку в начале и в конце числа, `Infinity` и `NaN`, а ещё строки, разбитые на несколько строк. Любой документ JSON — валидный JSON5, так что парсер JSON5 читает и обычный JSON.

```js
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` — та же [проблема больших чисел](https://jsonstatham.dev/ru/guides/json-big-numbers/), что и у `JSON.parse`. В Python есть пакет `json5` с той же идеей, а Jackson читает комментарии, если включить `JsonReadFeature.ALLOW_JAVA_COMMENTS`.

## Как оставить пометку в обычном JSON

- **Поле-комментарий:** `"_comment": "…"` или `"//": "…"`. Его примет любой парсер, но это данные: их видит каждый потребитель, схема с `additionalProperties: false` такое поле отвергнет, а второй `"//"` в том же объекте — повторный ключ, и большинство парсеров оставят только последний.
- **Схема:** `description` у каждого поля в JSON Schema файла (редакторы показывают его при наведении) или ключевое слово `$comment` для заметок внутри самой схемы.
- **Исходник с комментариями:** хранить в репозитории `config.jsonc` и собирать из него `config.json` при сборке.
- **Формат для людей:** если файл правят руками и комментарии важны, в YAML они есть изначально. Подробнее — [JSON или YAML](https://jsonstatham.dev/ru/guides/json-vs-yaml/) и [JSON в YAML](https://jsonstatham.dev/ru/json-to-yaml/).

```json
{
  "_comment": "порт для локальной разработки",
  "port": 8080
}
```

## Как убрать комментарии перед разбором

Если исходник должен хранить комментарии, а читатель строгий, комментарии вырезают при сборке или при загрузке. Для этого нужен токенизатор вроде [strip-json-comments](https://github.com/sindresorhus/strip-json-comments) или jsonc-parser, а не регулярное выражение: в `"https://example.com"` есть `//` внутри строки, и наивный шаблон разрежет её пополам.

```js
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](https://github.com/tailscale/hujson) от Tailscale: `hujson.Standardize` превращает JSON с комментариями и висячими запятыми в обычный JSON. В Python такие файлы сразу читает `json5.loads`.

[Валидатор](https://jsonstatham.dev/ru/validator/?sample=comment) здесь строгий: комментарий — это ошибка со своим кодом, строкой и столбцом, и ничего не вырезается втихую. С [висячей запятой](https://jsonstatham.dev/ru/errors/trailing-comma/) обращение такое же.

## Комментарии в JSON: частые вопросы

### Поддерживает ли JSON комментарии?

Нет. В RFC 8259 нет синтаксиса комментариев, и `JSON.parse`, модуль `json` в Python, `encoding/json` в Go и Jackson с настройками по умолчанию отвергают `//` и `/* */`. JSONC и JSON5 — отдельные форматы, где они разрешены.

### Как закомментировать строку в JSON?

Никак. Строку можно удалить, спрятать значение под ключ, который никто не читает (переименовать `"port"` в `"_port"`), или держать файл в JSONC и вырезать комментарии перед разбором. Осторожно с запятыми: если убрать последний элемент, останется [висячая запятая](https://jsonstatham.dev/ru/errors/trailing-comma/).

### Чем JSONC отличается от JSON5?

JSONC — это JSON плюс комментарии, а висячие запятые терпят лишь некоторые инструменты. JSON5 вдобавок разрешает ключи без кавычек, одинарные кавычки, шестнадцатеричные числа, `Infinity` и `NaN`. Обоим нужен свой парсер.

### Почему VS Code разрешает комментарии в settings.json, но не в моём файле?

Он открывает `settings.json` как «JSON with Comments», а остальные файлы `.json` — как строгий JSON. Менять режим или прописывать `files.associations` имеет смысл, только если программа, которая читает файл, тоже понимает комментарии.
