Масиви та об'єкти 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.