Что такое JSON: синтаксис, частые ошибки и как их найти

JSON (JavaScript Object Notation) появился как подмножество JavaScript, но давно стал независимым стандартом: на нём общаются веб-сервисы, мобильные приложения, конфигурации (package.json, composer.json), базы данных и логи. Разберём синтаксис, типичные ошибки и инструменты для работы с JSON.

Базовый синтаксис

JSON состоит из двух структур:

• объект — набор пар «ключ: значение» в фигурных скобках {};
• массив — упорядоченный список значений в квадратных скобках [].

{
  "name": "Анна Смирнова",
  "age": 29,
  "city": "Казань",
  "isActive": true,
  "skills": ["SQL", "Python", "Excel"],
  "address": {
    "street": "ул. Баумана, 1",
    "zip": "420111"
  },
  "manager": null
}

Правила:

• ключи — всегда строки в двойных кавычках;
• пары разделяются запятыми, после последней пары запятой нет;
• ключ и значение разделяет двоеточие;
• файл обычно в кодировке UTF-8 — кириллица допустима без экранирования.

Типы данных

В JSON нет типов «дата», undefined, NaN, Infinity, функций и комментариев. Даты обычно передают строкой в формате ISO 8601 ("2026-10-07T12:00:00Z") или числом — Unix-временем. Подробнее — в гайде Unix-время.

Экранирование в строках

Внутри строки специальные символы записываются через обратный слэш:

{
  "quote": "Он сказал: \"Привет\"",
  "path": "C:\\Users\\anna",
  "multiline": "Строка 1\nСтрока 2",
  "emoji": "\u263A"
}

Частые ошибки

1. Лишняя запятая в конце

{
  "a": 1,
  "b": 2,
}

Ошибка — запятая после "b": 2. В JavaScript это допустимо, в JSON — нет.

2. Одинарные кавычки или ключи без кавычек

{'name': 'Анна'}
{name: "Анна"}

Оба варианта невалидны. Правильно: {"name": "Анна"}.

3. Комментарии

{
  // порт сервера
  "port": 8080
}

Стандарт JSON не поддерживает комментарии. Если нужно пояснение, добавьте отдельное поле, например "_comment", или используйте формат, который их допускает (JSONC, YAML).

4. Неэкранированные символы

Кавычка или обратный слэш внутри строки без \ ломают разбор. Особенно часто это случается с путями Windows и HTML-кодом внутри JSON.

5. Числа как строки и наоборот

"age": "29" и "age": 29 — разные значения. Если API ожидает число, строка вызовет ошибку валидации. Номера телефонов, индексы и ИНН, наоборот, лучше хранить строками, чтобы не потерять ведущие нули.

6. Слишком большие числа

Многие парсеры (в том числе JavaScript) хранят числа как 64-битные числа с плавающей точкой и теряют точность выше 2^53 − 1 (9 007 199 254 740 991). Длинные идентификаторы передавайте строками.

7. BOM и невидимые символы

Файл, сохранённый с меткой порядка байтов (BOM) или с неразрывными пробелами из Word, может не читаться. Сохраняйте в UTF-8 без BOM.

Форматирование и проверка

Ответ API часто приходит одной длинной строкой. Чтобы его прочитать или найти ошибку, используйте JSON-форматтер:

• форматирование (pretty print) — отступы и переносы строк;
• минификация — удаление пробелов для экономии трафика;
• валидация — проверка синтаксиса с указанием строки и позиции ошибки.

В командной строке то же умеют стандартные инструменты:

# Python
python3 -m json.tool data.json

# jq
jq . data.json

JSON и CSV

Пример: одна и та же запись

name,city,age
Анна,Казань,29

[{"name": "Анна", "city": "Казань", "age": 29}]

Учтите, что в русской локали Excel по умолчанию использует точку с запятой как разделитель CSV, а запятую — как десятичный разделитель. Конвертировать данные в обе стороны можно в конвертере CSV в JSON.

Работа с JSON в коде

Почти во всех языках есть встроенные средства:

// JavaScript
const obj = JSON.parse('{"city": "Казань", "age": 29}');
const text = JSON.stringify(obj, null, 2); // с отступами

# Python
import json
data = json.loads('{"city": "Казань"}')
text = json.dumps(data, ensure_ascii=False, indent=2)

Обратите внимание на ensure_ascii=False в Python: без него кириллица превратится в последовательности вида \u041a\u0430.... Это корректный JSON, но читать такой файл неудобно.

JSON Schema

Для проверки не только синтаксиса, но и структуры данных используют JSON Schema — описание того, какие поля обязательны, какого они типа и в каких пределах. Схема помогает отлавливать ошибки в API ещё до того, как неверные данные попадут в базу.

JSON Lines и большие файлы

Для логов и больших выгрузок используют формат JSON Lines (.jsonl): каждая строка — отдельный JSON-объект. Такой файл можно читать построчно, не загружая целиком в память, и дописывать в конец. Обычный JSON-массив на несколько гигабайт открыть в редакторе почти невозможно, а JSON Lines обрабатывается утилитами вроде jq потоком.

JSON в SEO и вебе

На сайтах JSON встречается не только в API. Микроразметка Schema.org в формате JSON-LD — тоже JSON, и все правила выше к ней относятся: одна лишняя запятая — и поисковик не увидит разметку. Подробнее — в гайде Микроразметка Schema.org.

Чек-лист

• Все ключи и строки в двойных кавычках.
• Нет запятой после последнего элемента.
• Нет комментариев.
• Спецсимволы в строках экранированы.
• Длинные числа и идентификаторы с ведущими нулями — строками.
• Файл в UTF-8 без BOM и проходит валидацию.