# JSON — структуровані дані для програм, API та AI-агентів
> Повний практичний посібник з формату JSON: синтаксичні правила, серіалізація через parse/stringify, робота з REST API, JSON Schema та структурований вивід для штучного інтелекту.
## 1. Що таке JSON і чому він став стандартом
Формат **JSON** (*JavaScript Object Notation*) є універсальним стандартом для обміну структурованими даними між вебсерверами, клієнтськими застосунками, базами даних та сучасними AI-агентами.
Коли комп'ютерні програми взаємодіють між собою, передавати інформацію звичайним неструктурованим текстом неефективно:
> *«Олена Ковальчук, 29 років, Київ, преміум-підписка активна, навички: Python, SQL.»*
Людина легко зрозуміє цей опис, але алгоритм витратить значні ресурси на розпізнавання сутностей. У форматі JSON ті самі дані виглядають суворо та детерміновано:
```json
{
"id": 1042,
"name": "Олена Ковальчук",
"age": 29,
"city": "Київ",
"isPremium": true,
"skills": ["Python", "SQL"]
}
```
Будь-який парсер на будь-якій мові програмування (JavaScript, Python, Go, Rust) миттєво зчитає ключ `"city"` та отримає значення `"Київ"` без двозначностей.
```mermaid
flowchart LR
A["Клієнтський UI
(React / Mobile App)"] -->|HTTP POST JSON| B["REST API Сервер
(Node.js / Python)"]
B -->|SQL / NoSQL JSONB| C["База даних
(PostgreSQL / MongoDB)"]
B -->|Structured Output JSON| D["LLM / AI-Агент
(Claude / OpenAI)"]
```
### Чому JSON не залежить від JavaScript
Попри свою назву, JSON є абсолютно мовно-незалежним текстовим форматом. Він має власний RFC-стандарт (RFC 8259) та підтримується всіма сучасними екосистемами через стандартний MIME-тип `application/json`.
---
## 2. Анатомія JSON: синтаксис об’єктів, масивів та примітивів
Усі дані у форматі JSON будуються навколо двох ключових контейнерів (об'єктів і масивів) та шести базових типів значень.
### Об’єкт (JSON Object)
Об'єкт представляє невпорядкований набір пар `ключ: значення`, що обов'язково беруться у фігурні дужки `{}`. Ключем завжди має бути текстовий рядок у подвійних лапках.
```json
{
"username": "alex_dev",
"email": "alex@example.com",
"role": "admin"
}
```
### Масив (JSON Array)
Масив — це впорядкований список значень будь-якого типу, взятий у квадратні дужки `[]`. Елементи масиву індексуються з нуля.
```json
{
"supportedLocales": ["uk", "en", "es", "de"],
"primeNumbers": [2, 3, 5, 7, 11]
}
```
### Допустимі типи значень (Values)
У JSON дозволено використовувати рівно 6 типів значень:
| Тип значення | Опис та правила запису | Приклад |
| :--- | :--- | :--- |
| **Рядок (String)** | Послідовність символів Unicode у подвійних лапках | `"Hello, World!"` |
| **Число (Number)** | Ціле або дробове число (без лапок, без шістнадцяткових) | `42`, `-12.5`, `1.5e3` |
| **Логічне (Boolean)** | Тільки символи в нижньому регістрі: `true` або `false` | `true`, `false` |
| **Null** | Позначення свідомої відсутності значення | `null` |
| **Об'єкт (Object)** | Вкладений контейнер пар ключ-значення | `{"nested": true}` |
| **Масив (Array)** | Вкладений список елементів | `[1, 2, 3]` |
---
## 3. Суворі правила синтаксису та типові пастки
Синтаксис JSON набагато суворіший, ніж гнучкий синтаксис JavaScript або Python. Помилка навіть в одному символі ламає валідацію всього документа.
### П'ять головних правил синтаксису
1. **Тільки подвійні лапки:** Ключі та текстові рядки зобов'язані бути в `"подвійних лапках"`. Одинарні лапки `'text'` викликають фатальну помилку парсера.
2. **Жодних висячих ком (Trailing Commas):** Після останнього елемента об'єкта або масиву ставити кому категорично заборонено.
3. **Двокрапка як єдиний роздільник:** Ключ відокремлюється від значення виключно двокрапкою `:`.
4. **Повна відсутність коментарів:** Специфікація JSON не підтримує коментарі `//` чи `/* */`. Будь-які пояснення мають оформлюватися як звичайні поля документа (наприклад, `"_comment": "Пояснення"`).
5. **Заборонені типи даних:** У JSON не можна передавати `undefined`, `NaN`, `Infinity`, регулярні вирази чи функції.
### Порівняння валідного та невалідного JSON
:::tabs
@tab Валідний приклад
```json
{
"product": "MacBook Pro",
"price": 1999.99,
"inStock": true,
"tags": ["laptop", "apple", "m-series"]
}
```
@tab Невалідний приклад (Типові помилки)
```json
{
product: 'MacBook Pro', // Помилка: одинарні лапки та ключ без лапок
"price": 1999.99,
"inStock": true,
"tags": ["laptop", "apple",], // Помилка: висяча кома
} // Помилка: висяча кома перед закриваючою дужкою
```
:::
---
## 4. Відмінності між JSON та об’єктами JavaScript
Початківці часто плутають об'єктний літерал JavaScript і формат JSON. Проте між ними є принципова різниця.
```mermaid
flowchart TD
subgraph Текстовий_Рядок["JSON (Символьний потік)"]
J["'{\"name\":\"Max\",\"age\":30}'"]
end
subgraph Пам'ять_Програми["JavaScript Object (Структура в RAM)"]
O["{ name: 'Max', age: 30 }"]
end
J -->|JSON.parse| O
O -->|JSON.stringify| J
```
### Таблиця фундаментальних відмінностей
| Характеристика | Об'єкт JavaScript | JSON (Текстовий формат) |
| :--- | :--- | :--- |
| **Форма існування** | Жива структура даних в оперативній пам'яті | Текстовий рядок (послідовність байтів) |
| **Вимоги до ключів** | Можуть бути без лапок або Symbol | Обов'язково рядки у подвійних лапках |
| **Підтримувані типи** | Функції, методи, `Date`, `Map`, `Set`, `undefined` | Лише 6 базових типів (рядки, числа, bool, null, obj, arr) |
| **Коментарі** | Дозволені `//` та `/* */` | Повністю заборонені |
| **Висячі коми** | Дозволені сучасними стандартами JS | Суворо заборонені стандартом |
---
## 5. Навігація та читання вкладених структур даних
У реальних проєктах відповіді API містять глибокі ієрархічні структури. Для доступу до конкретного значення застосовують точкову нотацію (`.`) для об'єктів та індекси (`[]`) для масивів.
### Приклад складного документа
```json
{
"orderId": "ORD-94821",
"customer": {
"fullName": "Тарас Шевченко",
"contacts": {
"email": "taras@example.org",
"phones": ["+380501112233", "+380679998877"]
}
},
"items": [
{ "id": 1, "title": "Монітор 4K", "price": 450, "qty": 1 },
{ "id": 2, "title": "Механічна клавіатура", "price": 120, "qty": 2 }
]
}
```
### Шляхи звернення до елементів
- `order.orderId` $\rightarrow$ повертає `"ORD-94821"`
- `order.customer.fullName` $\rightarrow$ повертає `"Тарас Шевченко"`
- `order.customer.contacts.phones[0]` $\rightarrow$ повертає перший номер `"+380501112233"`
- `order.items[1].price` $\rightarrow$ повертає ціну другого товару `120`
> [!TIP]
> У сучасному JavaScript для запобігання помилкам `TypeError: Cannot read properties of undefined` завжди використовуйте опціональні ланцюжки: `order?.customer?.contacts?.email`.
---
## 6. JSON у REST API: запити, відповіді та заголовки
Практично всі сучасні вебсервіси використовують JSON як протокол передачі корисного навантаження (Payload) через протокол HTTP.
```mermaid
sequenceDiagram
autonumber
actor Client as Клієнт (Браузер / Додаток)
participant Server as REST API Сервер
Note over Client: Підготовка об'єкта та серіалізація
Client->>Server: POST /api/users (Header: Content-Type: application/json)
Note over Server: Десеріалізація JSON, валідація, запис у БД
Server-->>Client: 201 Created (Header: Content-Type: application/json)
Note over Client: Читання response.json()
```
### Ключові HTTP-заголовки
1. **`Content-Type: application/json`:** вказує серверу або клієнту, що в тілі запиту (Request Body) або відповіді (Response Body) передається валідний JSON-рядок.
2. **`Accept: application/json`:** клієнт повідомляє серверу, що очікує отримати відповідь виключно у форматі JSON (а не XML чи HTML).
---
## 7. Серіалізація та десеріалізація: parse і stringify
Перетворення живих об'єктів пам'яті на текст називається **серіалізацією** (*Serialization*), а зворотне перетворення тексту на об'єкт — **десеріалізацією** (*Deserialization*).
:::tabs
@tab JavaScript / TypeScript
```typescript
// 1. Десеріалізація (Текст -> Об'єкт)
const jsonString = '{"title":"Ноутбук","price":1200}';
const product = JSON.parse(jsonString);
console.log(product.title); // "Ноутбук"
// 2. Серіалізація (Об'єкт -> Текст)
const user = { name: "Данило", active: true };
const serialized = JSON.stringify(user, null, 2); // форматування з відступом у 2 пробіли
```
@tab Python
```python
import json
# 1. Десеріалізація
raw_text = '{"title": "Ноутбук", "price": 1200}'
product = json.loads(raw_text)
print(product["title"])
# 2. Серіалізація
user_dict = {"name": "Данило", "active": True}
json_string = json.dumps(user_dict, indent=2, ensure_ascii=False)
```
@tab Go
```go
package main
import (
"encoding/json"
"fmt"
)
type Product struct {
Title string `json:"title"`
Price int `json:"price"`
}
func main() {
raw := []byte(`{"title":"Ноутбук","price":1200}`)
var p Product
json.Unmarshal(raw, &p)
fmt.Println(p.Title)
}
```
:::\n
---
## 8. Діагностика помилок синтаксису та валідація
Якщо текст містить хоча б одну синтаксичну помилку, виклик `JSON.parse()` викидає виняток `SyntaxError`, що може аварійно зупинити роботу додатку.
```javascript
try {
const data = JSON.parse(untrustedUserInput);
} catch (error) {
console.error("Невалідний JSON:", error.message);
}
```
### Чек-лист швидкої діагностики
- [ ] Чи закриті всі фігурні `{}` та квадратні `[]` дужки?
- [ ] Чи всі ключі взяті саме у подвійні лапки `""`?
- [ ] Чи немає висячої коми перед останньою дужкою?
- [ ] Чи не потрапили до тексту значення `undefined`, `NaN` або коментарі?
- [ ] Чи екрановані внутрішні лапки у рядках: `"quote": "Слово \"у лапках\""`?
---
## 9. JSON Schema: перевірка контрактів і структури
Синтаксично коректний JSON ще не гарантує, що дані мають правильну бізнес-структуру. Якщо API очікує число `age`, а отримує рядок `"двадцять"`, програма впаде на етапі обчислень.
Для формального опису вимог до структури використовується стандарт **JSON Schema**.
```json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "UserRegistrationSchema",
"type": "object",
"properties": {
"email": {
"type": "string",
"format": "email"
},
"age": {
"type": "integer",
"minimum": 18
},
"roles": {
"type": "array",
"items": { "type": "string" },
"minItems": 1
}
},
"required": ["email", "age"]
}
```
Будь-який валідатор (наприклад, Ajv у JavaScript чи jsonschema у Python) автоматично перевірить вхідні дані за цим контрактом ще до передачі в базу даних.
---
## 10. Структуровані дані для LLM, виклику функцій та AI-агентів
У сучасній розробці зі штучним інтелектом текстові відповіді у вільному форматі поступово поступаються місцем **Structured Outputs**.
AI-агенти (наприклад, Claude Code, OpenAI Function Calling, LangChain) використовують JSON для виклику зовнішніх інструментів:
```json
{
"name": "sendEmailNotification",
"arguments": {
"recipient": "user@example.com",
"subject": "Рахунок сформовано",
"invoiceId": "INV-2026-09"
}
}
```
### Як гарантувати повернення чистого JSON від мовної моделі
1. **Вказуйте схему у системному промпті:** Завжди передавайте точну TypeScript-модель або JSON Schema.
2. **Вимагайте сирий вивід:** Використовуйте інструкцію: *"Return ONLY a valid raw JSON object. Do not wrap in markdown code blocks or add introductory text."*
3. **Використовуйте режим Structured Outputs:** У провайдерів API (Anthropic Tool Use / OpenAI JSON Mode) вмикайте примусову схему валідації на рівні генератора токенів.
---
## 11. Порівняння форматів: JSON, YAML, XML та TOML
| Формат | Читабельність людиною | Підтримка коментарів | Обсяг розмітки | Основна сфера застосування |
| :--- | :--- | :--- | :--- | :--- |
| **JSON** | Середня / Висока | Ні | Мінімальний | Web API, клієнт-серверний зв'язок, виклики AI |
| **YAML** | Дуже висока | Так | Нульовий (відступи) | Конфігурації CI/CD (GitHub Actions, K8s) |
| **TOML** | Дуже висока | Так | Низький | Конфігурації проєктів (Cargo, pyproject.toml) |
| **XML** | Низька | Так | Високий (теги) | Спадкові enterprise-системи, SOAP, SVG |
---
## 12. Практичний воркшоп, самоперевірка та підсумковий чек-лист
Закріпимо всі здобуті навички на повному циклі: від отримання даних з API до валідації та читання.
### Повний сценарій отримання та читання даних
```typescript
// Отримання даних користувача через Fetch API
async function fetchUserProfile(userId: number) {
try {
const response = await fetch(`https://api.example.com/users/${userId}`, {
headers: { Accept: "application/json" }
});
if (!response.ok) {
throw new Error(`HTTP Error: ${response.status}`);
}
// Автоматична десеріалізація JSON
const user = await response.json();
// Безпечне читання значень
console.log(`Користувач: ${user.name}`);
console.log(`Основна навичка: ${user.skills?.[0] ?? 'відсутня'}`);
return user;
} catch (err) {
console.error("Помилка отримання профілю:", err);
}
}
```
### Швидка самоперевірка
> **1. Яка помилка виникне, якщо у файлі JSON використати одинарні лапки для рядка?**
>
> > [!TIP]
> > **Відповідь:** Станеться помилка парсингу `SyntaxError: Unexpected token ' in JSON`. Специфікація JSON дозволяє виключно подвійні лапки `""`.
> **2. Чому після останнього елемента в об'єкті JSON не можна ставити кому?**
>
> > [!TIP]
> > **Відповідь:** Стандарт JSON забороняє висячі коми (trailing commas). Парсер очікує після коми наступну пару ключ-значення, і якщо знаходить закриваючу дужку `}`, виникає фатальна помилка синтаксису.
> **3. Для чого потрібен стандарт JSON Schema?**
>
> > [!TIP]
> > **Відповідь:** Щоб перевіряти бізнес-структуру та типи даних у документі (наявність обов'язкових полів, мінімальні значення чисел, формат email), а не лише базову валідність синтаксису.
### Підсумковий чек-лист роботи з JSON
- [ ] Усі рядки та ключі оформлено у подвійних лапках `""`.
- [ ] Перевірено відсутність висячих ком перед `}` та `]`.
- [ ] Вилучено всі коментарі з тіла JSON-документа.
- [ ] Під час передачі мережею встановлено заголовок `Content-Type: application/json`.
- [ ] Усі операції `JSON.parse()` захищено блоком `try/catch`.
- [ ] Для складних інтеграцій та AI-агентів створено контракт валідації через `JSON Schema`.