Комментарии в JSON: «Unexpected token / in JSON»
Обновлено
Перевод: «неожиданный токен /». Комментарии — для кода. Здесь данные. В JSON вообще нет синтаксиса комментариев, ни //, ни /* */, поэтому строгий парсер считает первую косую черту символом, которому тут нечего делать, и останавливается.
Ошибка и исправление
Конфиг, в котором завелась пометка. В JavaScript и в файле .jsonc это нормально, в JSON — ошибка:
{
// только для локального запуска
"port": 8080,
"debug": true /* убрать перед релизом */
}Оба комментария удалить. Если пометка важна, храни её как данные, под ключом, который программа пропускает:
{
"_comment": "только для локального запуска",
"port": 8080,
"debug": true
}Можно ли вообще писать комментарии в JSON-файле и что такое JSONC и JSON5 — отдельный вопрос, ему посвящён гайд комментарии в JSON, JSONC и JSON5. Эта страница — об ошибке и о том, как от неё избавиться.
Почему комментарий ломает JSON
RFC 8259 перечисляет всё, из чего состоит текст JSON: шесть структурных символов, строки, числа, три литерала и незначащие пробельные символы — ровно пробел, таб, перевод строки и возврат каретки. Комментариев нет ни в списке, ни в грамматике, поэтому / может быть только неожиданным символом. Автор JSON убрал комментарии намеренно, когда увидел, что в них начали передавать инструкции для парсеров; формат без них читается одинаково в любом парсере.
Сообщения о комментариях в разных парсерах
Строчный комментарий на месте ключа, строка 2 примера { // note, и блочный перед документом, /* x */ {}. Слово «комментарий» почти никто не произносит.
| Парсер | Внутри объекта (строка 2) | Перед документом: /* x */ {} |
|---|---|---|
| Chrome, Edge, Node.js (V8) | Expected property name or '}' in JSON at position 4 (line 2 column 3) Перевод: «ожидалось имя свойства или }». | Unexpected token '/', "/* x */ {}" is not valid JSON Перевод: «неожиданный токен /, … невалидный JSON». |
| Node.js 18, старый Chrome (V8 10.2) | Unexpected token / in JSON at position 4 Перевод: «неожиданный токен / в JSON, позиция 4». | Unexpected token / in JSON at position 0 Перевод: «неожиданный токен / в JSON, позиция 0». |
| Firefox | JSON.parse: expected property name or '}' at line 2 column 3 of the JSON data Перевод: «ожидалось имя свойства или }». | JSON.parse: unexpected character at line 1 column 1 of the JSON data Перевод: «неожиданный символ». |
| Safari | JSON Parse error: Unrecognized token '/' Перевод: «нераспознанный токен /». | JSON Parse error: Unrecognized token '/' Перевод: то же. |
| Python | Expecting property name enclosed in double quotes: line 2 column 3 (char 4) Перевод: «ожидается имя свойства в двойных кавычках». | Expecting value: line 1 column 1 (char 0) Перевод: «ожидается значение». |
| Go (encoding/json) | invalid character '/' looking for beginning of object key string Перевод: «недопустимый символ / там, где ищется начало ключа». | invalid character '/' looking for beginning of value Перевод: «недопустимый символ / там, где ищется начало значения». |
| Java (Jackson 2) | Unexpected character ('/' (code 47)): maybe a (non-standard) comment? (not recognized as one since Feature 'ALLOW_COMMENTS' not enabled for parser) Перевод: «неожиданный символ /: может быть, (нестандартный) комментарий? Не распознан, потому что функция ALLOW_COMMENTS не включена». | То же сообщение, строка 1, колонка 1 |
| C# (System.Text.Json) | '/' is invalid after a value. Expected either ',', '}', or ']'. Перевод: «/ недопустим после значения, ожидалась , } или ]». | '/' is an invalid start of a value. Перевод: «/ не может начинать значение». |
| C# (Newtonsoft.Json) | Ошибки нет: комментарии пропускаются | Ошибки нет: комментарии пропускаются |
| PHP (json_decode) | Syntax error, json_last_error() 4. Перевод: «синтаксическая ошибка». | Syntax error, json_last_error() 4. Перевод: «синтаксическая ошибка». |
| Rust (serde_json) | key must be a string at line 2 column 3 Перевод: «ключ должен быть строкой». | expected value at line 1 column 1 Перевод: «ожидалось значение». |
| jq | jq: parse error: Invalid numeric literal at line 2, column 5 Перевод: «неверный числовой литерал». | jq: parse error: Invalid numeric literal at line 1, column 3 Перевод: «неверный числовой литерал». |
| Visual Studio Code | Comments are not permitted in JSON., проблема 521. Перевод: «комментарии в JSON не допускаются». | Comments are not permitted in JSON., проблема 521. Перевод: то же. |
Комментарий узнают только Jackson и Visual Studio Code; «invalid after a value» от System.Text.Json сразу после { просто сбивает с толку. Проверено запуском: Node.js 18, 24 и 25.1, Safari 27, Python 3.9 и 3.14, Go 1.25–1.27, Jackson 2.22 и 3.2, System.Text.Json и Newtonsoft.Json 13.0.4, PHP 8.3 и 8.5, serde_json 1.0, jq 1.7 и 1.8. Firefox и Visual Studio Code — по исходному коду; сообщения Firefox есть и в справочнике Mozilla.
Файлы, похожие на JSON, где комментарии можно
- Настройки Visual Studio Code (
settings.json,launch.json) иtsconfig.json— это JSONC (JSON with Comments): комментарии там допустимы, потому что их читатели их пропускают. package.json— чистый JSON: npm читает его строгим парсером, и комментарий ломает установку.- Файлы
.json5— это JSON5, где тоже можно комментарии, одинарные кавычки и висячие запятые. - Скопируй что-нибудь из этих файлов в запрос к API или в строгий парсер — и комментарии станут ошибками.
Комментарий с #, как в YAML или в оболочке, не комментарий ни в одном из этих форматов; валидатор этого сайта сообщает о нём как о неожиданном символе.
Как читать JSON с комментариями в коде
Честных варианта два: убрать комментарии там, где файл создаётся, или читать его парсером, который понимает комментарии (у System.Text.Json для этого есть переключатель, см. документацию Microsoft). Нечестный вариант — регулярное выражение, и пример на Python показывает почему.
Python
import json
import re
text = '{\n // where to send reports\n "url": "https://example.com/hook"\n}'
naive = re.sub(r"//.*", "", text) # заодно режет "//example.com/hook"
try:
json.loads(naive)
except json.JSONDecodeError as e:
print(e.msg) # Invalid control character at: обрезанная строка упирается в перевод строки
import json5 # pip install json5: понимает комментарии
print(json5.loads(text)["url"]) # https://example.com/hookJavaScript
// npm install jsonc-parser: им Visual Studio Code читает свои настройки
import { parse } from "jsonc-parser";
const text = '{\n // where to send reports\n "url": "https://example.com/hook"\n}';
const errors = [];
console.log(parse(text, errors).url, errors.length); // https://example.com/hook 0Go
package main
import (
"encoding/json"
"fmt"
"github.com/tailscale/hujson"
)
func main() {
text := []byte("{\n // where to send reports\n \"url\": \"https://example.com/hook\"\n}")
std, err := hujson.Standardize(text) // убирает комментарии, сохраняя смещения байтов
var v map[string]string
fmt.Println(err, json.Unmarshal(std, &v), v["url"]) // <nil> <nil> https://example.com/hook
}C#
using System.Text.Json;
var options = new JsonDocumentOptions { CommentHandling = JsonCommentHandling.Skip };
using var doc = JsonDocument.Parse("{\n // local runs only\n \"port\": 8080\n}", options);
Console.WriteLine(doc.RootElement.GetProperty("port")); // 8080Java (Jackson)
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.node.ObjectNode;
// Пометки в данных переживут любой парсер; после чтения их убирают.
ObjectNode node = (ObjectNode) new ObjectMapper().readTree("{\"_comment\": \"local runs only\", \"port\": 8080}");
node.remove("_comment");
System.out.println(node); // {"port":8080}Jackson пропускает // и /* */ с включённой JsonReadFeature.ALLOW_JAVA_COMMENTS — это нынешнее имя функции ALLOW_COMMENTS из его сообщения об ошибке.
PHP
$data = json_decode('{"_comment": "local runs only", "port": 8080}', true);
unset($data['_comment']);
echo json_encode($data); // {"port":8080}Как не пускать комментарии в JSON
- Держать заметки для людей в отдельном документе или в ключах
"_comment", а не в комментариях. - Если конфигу правда нужны комментарии, называть его
.jsoncили.json5, чтобы и редактор, и люди знали, каким парсером его читать. - Удалять комментарии настоящим парсером JSONC, а не регулярным выражением:
//есть в каждом URL. - Проверять в валидаторе JSON тот файл, который уходит дальше, а не тот, что правишь.
Проверить в валидаторе
Открыть пример с комментарием в валидаторе JSON. Он сообщает код comment там, где начинается // или /*, если на этом месте ждали значение, ключ, запятую или скобку. После ключа он сообщит о пропущенном двоеточии, а после конца документа — о лишнем после JSON: именно этого парсер там и ждал.
Рядом: висячая запятая, комментарии в JSON, JSONC и JSON5 и все ошибки JSON.
Ошибка из-за комментария: частые вопросы
Поддерживает ли JSON комментарии?
Нет. В RFC 8259 синтаксиса комментариев нет. JSONC и JSON5 их добавляют, но это другие форматы, и читать их нужно своими парсерами.
Почему редактор принимает комментарии в settings.json?
Потому что этот файл — JSONC, и его читает парсер, пропускающий комментарии. В файлах, которые Visual Studio Code считает чистым JSON, он по-прежнему пишет «Comments are not permitted in JSON.».
Как оставить пометку в JSON-файле?
Данными: ключ вроде "_comment" со строковым значением. Его прочитает любой парсер, а программа просто пропустит этот ключ.
Можно ли удалять комментарии регулярным выражением?
Нет. // и /* встречаются внутри строк, прежде всего в URL, а регулярное выражение этого не различит. Используй парсер JSONC или JSON5.