JSON: синтаксис, ошибки парсинга и форматирование

JSON повсюду. Он лежит в основе REST API, конфигурационных файлов, выходных данных баз данных, webhook-событий и агрегаторов логов. Вы сталкиваетесь с ним десятки раз в день — разрабатывая бэкенд-сервис, отлаживая фронтенд-приложение или читая документацию. Глубокое понимание JSON — не просто умение его парсить, но и читать, валидировать, диагностировать — один из наиболее прибыльных навыков разработчика.

Это руководство охватывает всё: от основ синтаксиса JSON до отладки распространённых ошибок парсинга, стратегий форматирования и работы с глубоко вложенными структурами. Вставьте любой JSON в JSON Formatter BrowseryTools — он мгновенно валидирует и красиво форматирует его. Бесплатно, без регистрации, всё остаётся в браузере.

Почему JSON победил (а XML проиграл)

Прежде чем JSON стал стандартом обмена данными, правил XML. SOAP API, RSS-ленты и конфигурационные файлы — всё использовало XML. JSON появился как более простая альтернатива и постепенно занял место XML в большинстве сценариев. Причины очевидны:

• Меньше многословия — в JSON не нужны закрывающие теги. Те же данные занимают на 30–50% меньше символов.
• Нативен для JavaScript — JSON расшифровывается как JavaScript Object Notation. Он напрямую отображается на объекты и массивы JavaScript, что делает его парсинг и сериализацию тривиальными в браузере.
• Читаемость — правильно отформатированный JSON-документ легче читать, чем эквивалентный XML с угловыми скобками и объявлениями пространств имён.
• Широкая поддержка — в каждом крупном языке программирования есть встроенный парсер JSON. Не нужно устанавливать библиотеку только чтобы десериализовать ответ API.

У XML по-прежнему есть законные применения — форматы документов (DOCX, SVG), конфигурации, которым нужны комментарии (JSON их не поддерживает), и протоколы вроде SOAP, где XML обязателен. Но для API-взаимодействия и хранения данных JSON является безусловным победителем.

Правила синтаксиса JSON

JSON обладает небольшим строгим синтаксисом. Вот правила, которые чаще всего застают разработчиков врасплох:

• Ключи должны быть строками в двойных кавычках — {"name": "Alice"} допустимо; {name: "Alice"} — нет. В отличие от объектных литералов JavaScript, JSON не разрешает ключи без кавычек.
• Нет завершающих запятых — [1, 2, 3,] недопустимый JSON. Запятая после последнего элемента принята JavaScript и многими парсерами, но не является частью спецификации JSON.
• Нет комментариев — в JSON нет синтаксиса для комментариев. Это удивляет разработчиков, желающих аннотировать конфигурационные файлы. Если нужны комментарии, рассмотрите JSONC (JSON with Comments) или YAML.
• Строки только в двойных кавычках — строки в одинарных кавычках, например 'hello', недопустимы в JSON.
• Числа не могут начинаться с нуля — 007 недопустимо; используйте 7.
• Только шесть типов значений — строки, числа, булевы значения (true / false), null, объекты и массивы. Никаких дат, функций, undefined.

Распространённые ошибки JSON и их значение

Ошибки парсинга JSON могут быть загадочными. Вот наиболее частые из них и способы их исправления.

Unexpected token (неожиданный токен)

// Error: Unexpected token ' in JSON at position 9
{ "name": 'Alice' }

Одинарные кавычки недопустимы в JSON. Замените их двойными: {"name": "Alice"}.

Unexpected token } / ]

// Error: Unexpected token } in JSON at position 23
{
  "items": [1, 2, 3,]
}

Завершающая запятая перед закрывающей скобкой. Удалите запятую после последнего элемента. Это самая распространённая ошибка JSON для разработчиков, приходящих из JavaScript, где завершающие запятые вполне допустимы.

Unexpected end of JSON input (неожиданный конец входных данных)

Это означает, что JSON усечён — строка заканчивается до того, как все открытые объекты и массивы закрыты. Пересчитайте открывающие и закрывающие фигурные и квадратные скобки. Они должны совпадать.

Property names must be strings (имена свойств должны быть строками)

// Invalid — unquoted key
{ name: "Alice" }

// Valid
{ "name": "Alice" }

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

JSON можно представить двумя способами: красиво отформатированным (с отступами и переносами строк) или минифицированным (весь пробельный символ удалён). Выбор зависит от контекста.

Форматируйте, когда вы читаете, отлаживаете, просматриваете или храните JSON в системе контроля версий. Отформатированный JSON мгновенно читаем и чисто выглядит в diff Git, поскольку каждое значение находится на отдельной строке.

Минифицируйте, когда передаёте JSON по сети. Пробелы — чистые накладные расходы в HTTP-ответах. 100 КБ красиво отформатированного JSON могут ужаться до 60 КБ при минификации, а затем ещё до 15 КБ с gzip. Большинство API отдают минифицированный JSON по сети и дают клиенту форматировать его по необходимости.

В JavaScript: JSON.stringify(data, null, 2) форматирует с 2-пробельным отступом. JSON.stringify(data) минифицирует. JSON Formatter BrowseryTools умеет и то и другое — вставьте JSON и мгновенно переключайтесь между красивым и минифицированным видами.

Навигация по глубоко вложенному JSON

Реальные ответы API нередко глубоко вложены. Webhook-событие Stripe, ответ GitHub API или конфигурация Kubernetes могут иметь объекты на пять-шесть уровней вглубь. Вот стратегии работы с ними:

Используйте опциональную цепочку в JavaScript

// Without optional chaining — crashes if any level is undefined
const city = user.address.location.city;

// With optional chaining — returns undefined instead of throwing
const city = user?.address?.location?.city;

// With nullish coalescing for a default value
const city = user?.address?.location?.city ?? "Unknown";

Используйте jq для запросов к JSON в командной строке

# Pretty-print the entire response
curl https://api.example.com/users | jq .

# Extract a specific field
curl https://api.example.com/users | jq '.[0].email'

# Filter an array
curl https://api.example.com/users | jq '.[] | select(.active == true) | .name'

JSON в API и конфигурационных файлах

JSON служит двум очень разным целям в зависимости от контекста, и лучшие практики для них отличаются.

В ответах API JSON генерируется кодом и потребляется кодом. Вы редко пишете его вручную. Приоритет — корректность и согласованность: используйте библиотеку сериализации и доверьте ей экранирование. Минифицируйте для продакшена, включайте заголовок Content-Type application/json и версионируйте API, чтобы изменения структуры JSON не были ломающими.

В конфигурационных файлах (package.json, tsconfig.json, .eslintrc.json) JSON пишется людьми. Здесь важнее читаемость. Используйте отступ в 2 пробела, по возможности держите структуру неглубокой, и добавляйте комментарии через JSONC-совместимый парсер, если ваши инструменты его поддерживают. Никогда не минифицируйте конфигурационные файлы, хранящиеся в системе контроля версий.

Валидация с помощью JSON Schema

JSON Schema — спецификация для определения структуры, типов и ограничений JSON-документа. Она позволяет убедиться, что JSON-документ соответствует ожидаемой форме до того, как вы попытаетесь его использовать.

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": ["id", "name", "email"],
  "properties": {
    "id":    { "type": "integer" },
    "name":  { "type": "string", "minLength": 1 },
    "email": { "type": "string", "format": "email" },
    "age":   { "type": "integer", "minimum": 0, "maximum": 150 }
  },
  "additionalProperties": false
}

Библиотеки вроде ajv (JavaScript), jsonschema (Python) и JSON.NET Schema (.NET) могут валидировать JSON-документ по схеме во время выполнения — перехватывая некорректные документы на границе API до того, как они вызовут непредвиденные ошибки глубже в приложении.

Итоги

Простота JSON — его главная сила. Шесть типов значений, строгие правила кавычек, никаких комментариев, никаких завершающих запятых — ограничения невелики, а формат однозначен. Когда что-то идёт не так, это почти всегда одна из нескольких предсказуемых синтаксических ошибок. Вставьте сломанный JSON в JSON Formatter BrowseryTools — ошибка сразу станет видна с указанием точной позиции.