{"canonical_url":"https://engineer.company/uk/glossary/json/","content_markdown":"# JSON\n\n## Що це таке\n\nJSON — це текстовий запис даних фігурними й квадратними дужками, подвійними\nлапками та комами, завдяки якому програма майже будь-якою мовою прочитає саме\nте, що записала інша програма. Абревіатура розшифровується як JavaScript Object\nNotation: синтаксис запозичено з того, як JavaScript записує значення, проте\nдокумент JSON не прив'язаний до жодної мови. Файли зазвичай мають розширення\n`.json`, а в HTTP вміст позначають медіатипом `application/json`.\n\nУвесь формат уміщується на одній сторінці. Його словник складається з чотирьох\nпростих типів (рядки, числа, значення `true` і `false` та `null`) і двох\nскладених: об'єкта, тобто невпорядкованого набору пар «ім'я — значення», і\nмасиву, тобто впорядкованого списку. Будь-що можна вкласти в будь-що. Дати,\nдвійкові дані, коментарі й посилання між частинами документа залишено\nдомовленостям поза форматом.\n\nДуглас Крокфорд уперше описав формат у RFC 4627, опублікованому IETF у липні\n2006 року. Чинне визначення — RFC 8259 від грудня 2017 року. Воно узгоджене зі\nстандартом Ecma ECMA-404 щодо граматики й додає правила, які важать тоді, коли\nдані передають між двома системами: текст, що залишає замкнену екосистему, має\nбути в UTF-8, а відправник не має права додавати на початок мітку порядку байтів\n(BOM).\n\nXML старший і виразніший, з атрибутами, просторами імен і давньою традицією мов\nсхем. YAML у версії 1.2 став строгою надмножиною JSON і додав коментарі та легшу\nпунктуацію, яких хочуть у файлах, що їх редагують вручну. Двійкові формати на\nкшталт Protocol Buffers і CBOR жертвують читабельністю заради розміру й\nшвидкості.\n\n## Чому це важливо\n\nОбираючи JSON, команда насправді обирає контракт між двома системами: форму\nтого, що йде мережею, а іноді й форму того, що потрапляє до сховища.\n\nУ мережі JSON — вибір за замовчуванням, бо його вже розуміє все. Браузер\nрозбирає його без бібліотек, для кожної поширеної мови є зрілий парсер, а\nінженер, читаючи лог, бачить, що саме було в запиті. Ціна цього вибору лежить\nдеінде. Кожен запис повторює назви своїх полів, числа передаються десятковим\nтекстом, який треба розібрати назад, а сам формат мовчить про те, які поля\nобов'язкові та якого вони типу. Двійковий формат зі схемою, як-от Protocol\nBuffers, компактніший і швидше розбирається, а контракт перевіряє компілятор,\nале людині потрібен інструмент, щоб прочитати бодай одне повідомлення. Для\nпублічного API або такого, з яким говорить браузер, JSON — розумний вибір. Між\nвнутрішніми сервісами, де вирішують обсяг або затримка, баланс може схилитися в\nінший бік.\n\nЦю прогалину зазвичай закриває схема. JSON Schema описує, які властивості мусить\nмати об'єкт, яких вони типів і чи дозволені додаткові властивості, а OpenAPI\nспирається на неї, щоб описати цілий HTTP API. Схема — окремий документ, і вона\nточна лише доти, доки щось змушує її збігатися з кодом.\n\nУ сховищі питання в тому, чи належить структура до колонки JSON, чи до звичайних\nколонок. PostgreSQL має два типи. `json` зберігає точну копію вхідного тексту й\nрозбирає її заново щоразу, коли до неї звертається функція, а `jsonb` зберігає\nрозкладену двійкову форму: записувати її трохи повільніше, зате шукати в ній\nзначно швидше, і її можна індексувати. Документація радить `jsonb` для більшості\nзастосунків. Колонка JSON підходить для даних, форма яких змінюється від рядка\nдо рядка або належить клієнтові, наприклад для збережених налаштувань\nкористувача. Поле, за яким база має з'єднувати таблиці, накладати обмеження чи\nрахувати суму, заслуговує на власну колонку.\n\n## Як це виглядає на практиці\n\nНа одній платформі функції PostgreSQL самі збирають повну відповідь у JSON, а Go\nAPI\n[передає цей JSON від бази даних до браузера без змін](/uk/portfolio/designed-a-json-passthrough-from-postgres-to-api/).\nОбробник отримує його як `json.RawMessage` і пересилає далі, не декодуючи й не\nкодуючи повторно, а невеликий помічник `QueryJSON` зробив такий підхід\nстандартним. DTO, мапери й структури відповідей, які зазвичай накопичує\nбагатошаровий API, зникли. Коли функція починає повертати іншу форму, та\nдоходить до клієнта без жодної правки в коді обробника.\n\nЗбережений JSON створює іншу проблему, бо живе довше за код, який його записав.\nОдна платформа зберігає налаштування сповіщень та інші параметри як значення\nкористувача, накладені на набір типових значень, і спершу зливала їх лише на\nодному рівні. Ключа, який пізніше додали до типових значень, бракувало в кожному\nрядку, збереженому раніше, тож клієнтський код читав поле як undefined і падав,\nпричому саме в користувачів, які були з платформою найдовше. Рішенням стало\n[глибоке злиття, що використовує типові значення як каталог](/uk/portfolio/implemented-a-catalogue-driven-deep-merge/):\nкожен ключ із каталогу з'являється в результаті, зокрема вкладені, хоч би що\nмістив збережений блок. Міграція одразу застосувала це до наявних рядків, і\nфронтенд позбувся своїх захисних перевірок.\n\nДані також часто надходять просто як JSON. Історичні дані про електроенергію у\nформаті JSONL, по одній події JSON на рядок, треба було перетворити на погодинне\nспоживання для кожної зони, і\n[для цього створили три варіанти: на Python, JQ і SQL](/uk/portfolio/a-month-of-meter-readings-in-180-milliseconds/).\nНайшвидшим виявився Python: 34 мс для даних за один день і 180 мс за 30 днів.\n\n## Де виникають проблеми\n\nГраматика настільки мала, що парсери погоджуються щодо того, який текст\nкоректний. Проблеми народжуються в усьому, що граматика залишає відкритим.\n\n**Великий ідентифікатор повертається з іншою останньою цифрою.** Граматика не\nобмежує числа, але більшість парсерів, зокрема в JavaScript, читає їх як\n64-бітні числа з рухомою комою, які точно зберігають цілі лише до 2⁵³ − 1. RFC\n8259 називає діапазон від −(2⁵³ − 1) до 2⁵³ − 1 тим, у якому реалізації\nсходяться. За цією межею ідентифікатори змінюються без попередження:\n\n```js\nJSON.parse('{\"id\": 9007199254740993}').id;\n// 9007199254740992\n```\n\nНадсилайте 64-бітні ідентифікатори як рядки, а суми грошей — як рядки або як\nціле число найменших одиниць, але ніколи як число з рухомою комою.\n\n**Два сервіси читають той самий об'єкт по-різному.** RFC 8259 радить робити\nімена в об'єкті унікальними, а решту залишає відкритим: натрапивши на повторене\nім'я, багато парсерів залишають останнє значення, інші повідомляють про помилку,\nа деякі повертають усі пари. Коли шлюз перевіряє перше поле `role`, а бекенд діє\nза другим, перевірка нічого не захистила. Відхиляйте дубльовані імена там, де\nдані входять у систему. I-JSON, визначений у RFC 7493, — це профіль JSON, який\nїх забороняє.\n\n**Вручну відредагований файл перестає розбиратися.** Коментарі й кома після\nостаннього елемента лежать поза граматикою, тож перша людина, яка допише\nкоментар до конфігураційного файлу або залишить зайву кому, його зламає. Деякі\nінструменти приймають м'якший діалект, і тоді той самий файл коректний для\nодного читача й зламаний для наступного. Залиште JSON для даних, які пишуть\nмашини, а файлам, які люди підтримують вручну, дайте формат, створений для\nредагування, як-от YAML чи TOML.\n\n**Текст приходить спотвореним, або один парсер відкидає те, що приймає інший.**\nRFC 8259 вимагає UTF-8 між системами й забороняє мітку порядку байтів на\nпочатку. Граматика також допускає екранування на кшталт `\"\\uDEAD\"`, тобто\nполовину сурогатної пари без партнера, яку жоден коректний рядок Unicode\nвмістити не може, і бібліотеки поводяться з нею кожна по-своєму. Кодуйте в UTF-8\nбіля джерела й відкидайте некоректні послідовності на межі системи.\n\n**Один невеликий запит паралізує парсер.** Кілька кілобайтів вкладених дужок\nможуть завести рекурсивний парсер на тисячі рівнів углиб, а завеликий запит\nрозбирається повністю, перш ніж його побачить будь-яка схема. RFC 8259 дозволяє\nреалізації обмежувати і розмір тексту, і глибину вкладення, а API, що приймає\nJSON від сторонніх, має використати обидва: обмежити розмір запиту ще до\nчитання, глибину — під час розбору, і лише після цього перевіряти форму.\n\n## Що почитати далі\n\n- [RFC 8259: The JSON Data Interchange Format](https://www.rfc-editor.org/rfc/rfc8259)\n  — чинне визначення IETF із примітками про числа, дубльовані імена й кодування.\n- [ECMA-404: The JSON Data Interchange Syntax](https://ecma-international.org/publications-and-standards/standards/ecma-404/)\n  — стандарт Ecma для тієї самої граматики, на який RFC 8259 посилається як на\n  нормативний.\n- [RFC 7493: The I-JSON Message Format](https://www.rfc-editor.org/rfc/rfc7493)\n  — суворіший профіль, що вимагає UTF-8 і забороняє дубльовані імена.\n- [Специфікація JSON Schema](https://json-schema.org/specification) — словник,\n  яким оголошують, які властивості мусить мати документ.\n- [PostgreSQL: JSON Types](https://www.postgresql.org/docs/current/datatype-json.html)\n  — `json` проти `jsonb` і що кожен із них зберігає з початкового тексту.\n- [Go: json.RawMessage](https://pkg.go.dev/encoding/json#RawMessage) — тип, що\n  дає програмі на Go відкласти декодування або переслати JSON без змін.\n\n\u003chttps://engineer.company/uk/glossary/json/\u003e\n","date_modified":"2026-10-20T21:59:50Z","description":"Як працює JSON, коли API чи колонці бази даних варто його обрати і які пастки з дубльованими ключами, великими числами й кодуванням трапляються в роботі.","formats":{"gemtext":"https://engineer.company/uk/glossary/json/index.gmi","gopher":"https://engineer.company/uk/glossary/json/gophermap","html":"https://engineer.company/uk/glossary/json/","json":"https://engineer.company/uk/glossary/json/index.json","markdown":"https://engineer.company/uk/glossary/json/index.md","pdf":"https://engineer.company/uk/glossary/json/index.pdf"},"kind":"page","language":"uk","title":"Що таке JSON?","url":"https://engineer.company/uk/glossary/json/","version":1}