Что такое JSON: синтаксис, частые ошибки и проверка

JSON (JavaScript Object Notation) — это лёгкий текстовый формат для хранения и обмена структурированными данными. Он строится из объектов с парами «ключ/значение», упорядоченных массивов и нескольких типов значений: строк, чисел, true, false и null. JSON стал основным форматом веб-API и многих файлов конфигурации: его легко читать человеку и просто разбирать на любом языке программирования. При этом JSON строг: ключи и строки требуют двойных кавычек, а завершающие запятые и комментарии не допускаются.

Как выглядит JSON

JSON вырос из синтаксиса, которым JavaScript записывает литералы объектов, но от языка не зависит. Он описан в RFC 8259 и в стандарте ECMA-404, а краткая справка на json.org описывает всю грамматику целиком. Типичный документ выглядит так:

{
  "id": 1042,
  "name": "Ada Lovelace",
  "email": "ada@example.com",
  "active": true,
  "score": 98.5,
  "manager": null,
  "roles": ["admin", "editor"],
  "address": {
    "city": "London",
    "postcode": "N1 9GU"
  }
}

Пробельные символы между элементами (пробелы, табуляции и переводы строк) игнорируются, поэтому одни и те же данные можно записать в одну строку или разложить с отступами. На верхнем уровне JSON-документа может стоять любое значение, хотя API почти всегда используют объект или массив.

Типы данных JSON

Типа «дата» в JSON нет. Даты обычно записывают строками в формате ISO 8601, например "2026-10-13T09:30:00Z", или числами в виде меток времени Unix; наш конвертер Unix-времени переводит одно в другое.

Числа и точность

Стандарт JSON не ограничивает размер и точность чисел, но программы, которые его читают, ограничивают. JavaScript хранит числа как 64-битные числа с плавающей точкой, поэтому целые числа больше 9 007 199 254 740 991 (2⁵³ − 1) могут незаметно потерять точность. Для больших идентификаторов многие API передают их строками, например "id": "1234567890123456789".

Правила, на которых спотыкаются чаще всего

JSON похож на JavaScript, словари Python и YAML, поэтому люди так часто пишут некорректный JSON по ошибке. В стандартном JSON у этих правил нет исключений:

• Ключи должны быть строками в двойных кавычках. {name: "Ada"} — допустимый JavaScript, но недопустимый JSON; пишите {"name": "Ada"}.
• Только двойные кавычки. 'Ada' не является строкой JSON.
• Никаких завершающих запятых. [1, 2, 3,] и {"a": 1,} недопустимы.
• Никаких комментариев. Ни // ..., ни /* ... */ использовать нельзя.
• Литеральные значения пишутся в нижнем регистре. True, FALSE и None (написание из Python) недопустимы; используйте true, false и null.
• Никаких undefined, функций и особых чисел. В JavaScript они есть, но в JSON у них нет эквивалента.
• Ключи желательно делать уникальными. Стандарт рекомендует, чтобы имена внутри объекта были уникальны; при дубликатах парсеры ведут себя по-разному, и многие молча оставляют только последний.

Некоторые инструменты принимают смягчённые варианты. Такие файлы, как settings.json в VS Code и tsconfig.json в TypeScript, читаются парсерами, допускающими комментарии (этот вариант часто называют JSONC), а JSON5 допускает комментарии, одинарные кавычки и завершающие запятые. Это отдельные форматы: стандартный JSON-парсер, в том числе тот, что используют ваш API-клиент или сервер, их отвергнет.

Частые ошибки JSON и как их исправить

Формулировки ошибок у разных парсеров различаются. В таблице показаны сообщения, которые вы увидите в модуле json языка Python или в JSON.parse браузера, их обычный смысл и способ исправления. Указанная позиция часто оказывается сразу после настоящей ошибки, поэтому смотрите и на символ перед ней.

Последняя строка — одна из самых частых на практике: код вызывает JSON.parse или response.json() для страницы с ошибкой, которая начинается с <!DOCTYPE html>, и парсер сообщает о символе < как о неожиданном токене.

JSON, YAML и XML: сравнение

YAML 1.2 задумывался так, чтобы JSON-документы (за редкими исключениями) были и корректным YAML, поэтому преобразовывать их друг в друга просто. Наш конвертер JSON ↔ YAML работает в обе стороны, форматирование и валидация YAML и форматирование и валидация XML проверяют два других формата, а конвертер CSV ↔ JSON превращает выгрузки из таблиц в массивы объектов.

Форматирование и минификация

Поскольку пробельные символы незначимы, один и тот же JSON можно оформить для людей или для машин:

• Отформатированный JSON содержит переводы строк и отступы, обычно по два или четыре пробела, поэтому вложенность хорошо видна. Применяйте его для файлов конфигурации, документации и отладки.
• Минифицированный JSON убирает все необязательные пробельные символы, чтобы уменьшить объём. Применяйте его для данных, передаваемых по сети или хранимых в больших количествах; HTTP-сжатие тоже уменьшает размер, поэтому выигрыш часто скромный.

{"name":"Ada","roles":["admin","editor"],"active":true}

Большинство языков умеет и то и другое. В JavaScript JSON.stringify(data, null, 2) форматирует с отступом в два пробела, а JSON.stringify(data) минифицирует. В Python json.dumps(data, indent=2) форматирует, а json.dumps(data, separators=(",", ":")) даёт самый компактный вывод.

Как проверить JSON

У проверки JSON два уровня: является ли текст синтаксически корректным JSON вообще и соответствует ли он структуре, которую ожидает ваше приложение.

1. Проверьте синтаксис строгим парсером. Вставьте текст в наш инструмент форматирования и валидации JSON: он сообщает строку и столбец первой ошибки и работает прямо в браузере. В командной строке python3 -m json.tool data.json или jq . data.json выведет отформатированный документ или ошибку.
2. Исправляйте ошибки по одной. Парсер останавливается на первой проблеме, поэтому после каждого исправления запускайте проверку заново, пока она не пройдёт.
3. Проверьте структуру. Убедитесь, что обязательные поля существуют и имеют нужные типы: в коде или с помощью валидатора JSON Schema.
4. Проверьте кодировку. JSON, которым обмениваются системы, должен быть в UTF-8. Файл, сохранённый в другой кодировке, может давать странные символы или ошибки на тексте не на английском.

JSON Schema вкратце

JSON Schema — это словарь, написанный на самом JSON, для описания того, как должен выглядеть корректный документ: какие свойства обязательны, какого типа каждое из них, допустимые значения, шаблоны строк, диапазоны чисел и так далее. Валидаторы есть для большинства языков, а форматы описания API, такие как OpenAPI, используют JSON Schema для описания тел запросов и ответов. Спецификация опубликована на json-schema.org. Небольшой пример:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["id", "email"],
  "properties": {
    "id": { "type": "integer", "minimum": 1 },
    "email": { "type": "string", "format": "email" },
    "roles": { "type": "array", "items": { "type": "string" } }
  }
}

Документ без email или со строковым id был бы корректным JSON, но не прошёл бы проверку по этой схеме. Учтите, что многие валидаторы считают format лишь аннотацией и не применяют его, пока их не настроят.

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

Можно ли использовать комментарии в JSON?

Нет. Стандартный JSON не допускает комментариев в любом виде. Некоторые инструменты принимают JSONC или JSON5, где они разрешены, но файлы, которые будут читать другие программы, лучше оставлять в обычном JSON. Если нужна заметка, добавьте поле, например "_comment".

Почему в JSON нельзя ставить завершающие запятые?

Грамматику сознательно сделали минимальной, и завершающих запятых в ней просто нет. Многие движки JavaScript и другие языки принимают завершающие запятые в собственном синтаксисе, поэтому они так часто по ошибке попадают в JSON, написанный вручную.

Чем JSON отличается от объекта JavaScript?

JSON — это текстовый формат, а объект JavaScript — структура данных в памяти. Синтаксис JSON — более строгое подмножество синтаксиса литералов JavaScript. Преобразовывать одно в другое можно с помощью JSON.parse и JSON.stringify.

Что означает «Unexpected token < in JSON at position 0»?

Разбираемый текст начинается с <, а это почти всегда значит, что вместо JSON вы получили HTML, например страницу ошибки или входа. Проверьте URL запроса, код HTTP-статуса и необработанное тело ответа.

Сохраняется ли порядок ключей в объекте JSON?

Стандарт считает объекты неупорядоченными, поэтому полагаться на порядок ключей не стоит. На практике большинство современных парсеров сохраняют порядок, в котором читали ключи, но единственный порядок, который гарантирует JSON, — порядок элементов массива.

Какое расширение файла и MIME-тип у JSON?

Файлы имеют расширение .json, а медиатип — application/json, как зарегистрировано в RFC 8259.