JSON Toolkit

Массивы и объекты JSON: структура и вложенность для начинающих

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

Начинающий~6 мин чтенияОпубликовано 2026-11-20Обновлено 2026-11-20
Обложка введения в структуры массивов и объектов JSON

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

Первое: в JSON только два контейнера

Как бы сложен ни был ответ API, всё сводится к двум контейнерам и шести типам значений. Объект — это коллекция пар ключ/значение в фигурных скобках {}; массив — это упорядоченный список значений в квадратных скобках []. Значением может быть строка, число, true, false, null — или снова объект или массив. Объекты в массивах, массивы в объектах: эта рекурсия и есть вся выразительная сила JSON.

{
  "user": { "name": "Ada", "active": true },
  "roles": ["admin", "editor"],
  "lastLogin": null,
  "loginCount": 42
}

Отсюда практический вывод: перед запутанным payload не читайте его посимвольно. Сначала проверьте, какой символ внешний — { или [. Если объект, читайте его как именованные поля; если массив, читайте как список, а затем спускайтесь уровень за уровнем. Синтаксическая диаграмма на json.org умещается на одной странице именно потому, что две структуры плюс рекурсия покрывают всё.

Второе: как писать объекты, четыре жёстких правила

Объекты — то место, где новички ошибаются чаще всего, но правила сводятся к четырём:

  1. Ключи должны быть строками в двойных кавычках. {name: "Ada"} и {'name': 'Ada'} оба недопустимы; нужно писать {"name": "Ada"}. Литералы объектов JavaScript разрешают «голые» ключи и одинарные кавычки, JSON — нет; это самое частое смешение между ними.
  2. Разделяйте пары запятыми и никогда не оставляйте запятую после последней. {"a": 1, "b": 2,} падает с Unexpected token } на закрывающей скобке.
  3. Ключи должны быть уникальными. RFC 8259 формулирует это как SHOULD, а не MUST: дубликаты ключей не вызывают ошибки, но сохраняется ли первое или последнее значение, зависит от реализации, и языки расходятся. Никогда на это не полагайтесь.
  4. Порядок ключей не имеет значения. {"a":1,"b":2} и {"b":2,"a":1} — один и тот же объект; diff-инструменты и функции сравнения игнорируют порядок ключей. Если порядок важен, данные принадлежат массиву.

Третье: как писать массивы, порядок — это данные

Массивы хранят значения по позиции, и индексация начинается с 0: в ["admin", "editor"] строка "editor" — это [1]. Этот порядок значим — в этом суть разницы между массивами и объектами. Результаты поиска, отсортированные по релевантности, записи журнала по дате: эта информация живёт только в последовательности, и превращение в объект её уничтожает.

Две практические рекомендации. Во-первых, держите элементы однородными: [{"id":1},{"id":2}] потреблять гораздо легче, чем [1, "text", true] — это законно, но каждый потребитель вынужден проверять типы на каждом шаге. Во-вторых, пустой массив [] — совершенно допустимое значение: когда поле списка ещё не имеет содержимого, отдавайте [], а не null, чтобы потребителю не пришлось проверять существование, а затем пустоту.

[
  { "city": "Tokyo", "population": 13960000 },
  { "city": "Delhi", "population": 16780000 }
]

Четвёртое: вложенность, четыре формы настоящих payload

Реальные данные — это лишь два контейнера, вложенные друг в друга, а паттерны сводятся к четырём формам:

Форма Как выглядит Типичное применение
Объект содержит массив {"tags": ["a","b"]} Списковое поле сущности
Массив объектов [{"id":1},{"id":2}] Списки записей, постраничные результаты
Объект содержит объект {"db": {"host": "..."}} Группированная конфигурация, адресные блоки
Массив массивов [[1,2],[3,4]] Матрицы, строки таблицы

Типичный ответ API использует объект как оболочку и массив как содержимое:

{
  "code": 0,
  "data": {
    "items": [
      { "id": 1, "title": "first" },
      { "id": 2, "title": "second" }
    ],
    "page": 1,
    "total": 2
  }
}

Не вкладывайте ради вложенности. После трёх-четырёх уровней пути доступа становятся нечитаемыми, а код потребителя разбухает параллельно. Поля, которые всегда путешествуют вместе, принадлежат подобъекту: замените addrCity и addrZip на address: {city, zip}.

Пятое: объект или массив, таблица решений

Вопрос Ответ Почему
У каждого значения есть имя? Объект Доступ по ключу; добавление или удаление полей ничего не ломает
Это список похожих записей? Массив Порядок важен; можно map и filter
Нужен быстрый поиск по ключу? Объект, индексированный идентификатором Доступ O(1) вместо обхода
Несколько атрибутов одной сущности? Объект Атрибуты не имеют собственного порядка
Растущая коллекция похожих элементов? Массив Длина свободно растягивается

Один антипаттерн заслуживает отдельного упоминания: имитировать массив объектом с ключами "0", "1", "2". Он парсится без ошибок, но вы теряете семантику длины и инструменты итерации настоящего массива, а потребители вынуждены сортировать Object.keys, прежде чем хоть что-то прочитать. Если ключи — последовательные номера, пишите настоящий массив. Верно и обратное: список пар ключ/значение вроде [{"key":"theme","value":"dark"}] хуже объекта {"theme": "dark"} — если только ключи не по-настоящему динамические и их нельзя объявить заранее.

Шестое: три частые ошибки и их сообщения

Ошибочная форма Типичная ошибка Исправление
Висячая запятая {"a":1,} Unexpected token } Удалить последнюю запятую
Одинарные кавычки / голые ключи {name:'Ada'} Unexpected token ' / Expected property name Двойные кавычки для ключей и строк, всегда
Литералы Python True / None Unexpected token T Заменить на true / null
Фальшивый массив с числовыми ключами Без ошибки, семантика неверна Переписать как настоящий массив

Две привычки отладки: парсеры обычно указывают позицию после виновного символа, поэтому увидев position 42, посмотрите на один-два символа назад; а огромный однострочный JSON сначала форматируйте — номера строк и колонок каждый раз побеждают смещения символов. Полный каталог ошибок — в таблице поиска ошибок JSON, пошаговый процесс разбора — в как исправить ошибки парсинга JSON.

Седьмое: после написания проверьте структуру

JSON, написанный вручную, всегда должен пройти через парсер до сдачи. Легчайшая проверка — одна строка команды:

python3 -m json.tool config.json > /dev/null && echo OK
jq empty config.json && echo OK

Онлайн вставьте содержимое на страницу форматирования и валидации JSON — синтаксические ошибки вернутся со строкой и колонкой. Переключитесь в древовидный вид, чтобы увидеть тип каждого уровня с одного взгляда: не интерпретировано ли число как строка, совпадают ли длины массивов. А когда аудитория нетехническая, payload «массив объектов» можно развернуть в строки и колонки на странице JSON в таблицу — заодно проверится, что ваши данные действительно образуют регулярный список записей.

Вопросы о поле, которое должно было быть массивом, или о переделке слишком глубокой вложенности относятся к моделированию типов — следующее чтение: шесть типов, точность чисел и ловушки кодировки.

Можно ли преобразовывать массивы и объекты JSON друг в друга?

Да, но не без потерь. Преобразовать объект в массив обычно значит превратить ключи в значения и потерять доступ по ключу; преобразовать массив в объект требует придумать ключ для каждого элемента, и происхождение этих ключей — новая задача проектирования. Решайте по тому, как потребитель читает данные, а не по синтаксическому удобству.

Могут ли ключи объекта дублироваться?

Синтаксически да — RFC 8259 говорит лишь, что ключи СЛЕДУЕТ делать уникальными. Но JavaScript сохраняет последнее значение, тогда как некоторые библиотеки семейства C сохраняют первое: поведение различается между парсерами. В подписях, diff или хэшах дубликаты ключей дают прямые расхождения. Избегайте их на стороне производителя и относитесь к дубликатам из неизвестного источника как к риску на стороне потребителя.

Может ли массив содержать значения разных типов?

Синтаксически да: [1, "a", true] — валидный JSON. Но неоднородные массивы вынуждают проверять типы на каждой позиции в коде потребителя, и их трудно выразить в схеме. Кроме матриц и кортежей, где позиция и есть семантика, держите массивы однородными.

Почему {name:'json'} не проходит валидацию?

Потому что JSON требует двойных кавычек вокруг каждого ключа и каждого строкового значения. {name:'json'} — это литерал объекта JavaScript, а не JSON. Замените на {"name": "json"}, и валидация пройдёт. Одинарные кавычки, голые ключи и комментарии принадлежат диалектам вроде JSON5/JSONC, которым нужны собственные парсеры вместо стандартного JSON.parse.