ENRU

Комментарии в 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».
FirefoxJSON.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 Перевод: «неожиданный символ».
SafariJSON Parse error: Unrecognized token '/' Перевод: «нераспознанный токен /».JSON Parse error: Unrecognized token '/' Перевод: то же.
PythonExpecting 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 Перевод: «ожидалось значение».
jqjq: parse error: Invalid numeric literal at line 2, column 5 Перевод: «неверный числовой литерал».jq: parse error: Invalid numeric literal at line 1, column 3 Перевод: «неверный числовой литерал».
Visual Studio CodeComments 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/hook

JavaScript

// 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 0

Go

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")); // 8080

Java (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.