# 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
Несмотря на наличие "JavaScript" в названии, JSON представляет собой полностью языко-независимый текстовый формат, зафиксированный международным стандартом 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 всегда применяйте оператор опциональной последовательности (`order?.customer?.contacts?.email`), чтобы избежать падения программы с ошибкой `TypeError: Cannot read properties of undefined`.
---
## 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`:** указывает получателю, что тело запроса или ответа содержит сериализованный 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)
}
```
:::
---
## 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 не гарантирует соблюдения бизнес-правил (например, поле возраста может содержать строку `"двадцать"` вместо целого числа).
**JSON Schema** — общепринятый стандарт для описания структуры и валидации данных в формате JSON.
```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 в Node.js или 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 fences or include conversational commentary."*
3. **Используйте режим Structured Outputs:** Активируйте провайдерские опции JSON Mode (например, Anthropic Tool Use или OpenAI Structured Outputs) для грамматического контроля генерации токенов.
---
## 11. Сравнение форматов: JSON, YAML, XML и TOML
| Формат | Читаемость человеком | Поддержка комментариев | Объем разметки | Основная сфера применения |
| :--- | :--- | :--- | :--- | :--- |
| **JSON** | Средняя / Высокая | Нет | Минимальный | Веб-API, обмен данными клиент-сервер, вызов инструментов ИИ |
| **YAML** | Очень высокая | Да | Нулевой (на отступах) | Конфигурации CI/CD (GitHub Actions, Kubernetes) |
| **TOML** | Очень высокая | Да | Низкий | Конфигурации проектов (Cargo, pyproject.toml) |
| **XML** | Низкая | Да | Высокий (теги) | Корпоративные системы, SOAP, векторная графика SVG |
---
## 12. Практический воркшоп, самопроверка и итоговый чек-лист
Закрепим теоретические концепции на практическом сквозном сценарии.
### Комплексный сценарий получения и разбора данных
```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`. Спецификация формата допускает исключительно двойные кавычки `""`.
> **2. Почему в объектах и массивах JSON запрещены висячие запятые?**
>
> > [!TIP]
> > **Ответ:** Стандарт RFC 8259 строго запрещает запятые после последних элементов. Парсер ожидает после запятой следующее поле, и встретив закрывающую скобку `}`, генерирует фатальный сбой.
> **3. В чем назначение стандарта JSON Schema?**
>
> > [!TIP]
> > **Ответ:** В формальной проверке бизнес-контрактов и типов данных (наличие обязательных полей, диапазоны чисел, формат email), а не только базового соответствия синтаксису.
### Итоговый чек-лист работы с JSON
- [ ] Все строковые литералы и ключи оформлены строго в двойных кавычках `""`.
- [ ] Проверено отсутствие висячих запятых перед `}` и `]`.
- [ ] Из тела документа удалены все комментарии.
- [ ] При отправке по сети выставлен заголовок `Content-Type: application/json`.
- [ ] Все вызовы `JSON.parse()` изолированы защитным блоком `try/catch`.
- [ ] Для распределенных сервисов и AI-агентов определен контракт валидации через `JSON Schema`.