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

JSON даёт вам только два контейнера: объект несёт именованные поля, массив несёт упорядоченные списки — и почти каждый сломанный payload объясняется кавычками, запятыми или списком, записанным как фальшивый объект.
Первое: в JSON только два контейнера
Как бы сложен ни был ответ API, всё сводится к двум контейнерам и шести типам значений. Объект — это коллекция пар ключ/значение в фигурных скобках {}; массив — это упорядоченный список значений в квадратных скобках []. Значением может быть строка, число, true, false, null — или снова объект или массив. Объекты в массивах, массивы в объектах: эта рекурсия и есть вся выразительная сила JSON.
{
"user": { "name": "Ada", "active": true },
"roles": ["admin", "editor"],
"lastLogin": null,
"loginCount": 42
}
Отсюда практический вывод: перед запутанным payload не читайте его посимвольно. Сначала проверьте, какой символ внешний — { или [. Если объект, читайте его как именованные поля; если массив, читайте как список, а затем спускайтесь уровень за уровнем. Синтаксическая диаграмма на json.org умещается на одной странице именно потому, что две структуры плюс рекурсия покрывают всё.
Второе: как писать объекты, четыре жёстких правила
Объекты — то место, где новички ошибаются чаще всего, но правила сводятся к четырём:
- Ключи должны быть строками в двойных кавычках.
{name: "Ada"}и{'name': 'Ada'}оба недопустимы; нужно писать{"name": "Ada"}. Литералы объектов JavaScript разрешают «голые» ключи и одинарные кавычки, JSON — нет; это самое частое смешение между ними. - Разделяйте пары запятыми и никогда не оставляйте запятую после последней.
{"a": 1, "b": 2,}падает сUnexpected token }на закрывающей скобке. - Ключи должны быть уникальными. RFC 8259 формулирует это как SHOULD, а не MUST: дубликаты ключей не вызывают ошибки, но сохраняется ли первое или последнее значение, зависит от реализации, и языки расходятся. Никогда на это не полагайтесь.
- Порядок ключей не имеет значения.
{"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.