# JSON — dane ustrukturyzowane dla aplikacji, API i agentów AI
> Kompletny praktyczny przewodnik po formacie JSON: zasady składniowe, serializacja za pomocą parse/stringify, praca z REST API, JSON Schema oraz strukturalne wyjście dla sztucznej inteligencji.
## 1. Czym jest JSON i dlaczego stał się standardem
Format **JSON** (*JavaScript Object Notation*) to uniwersalny standard wymiany danych strukturalnych między serwerami webowymi, aplikacjami klienckimi, bazami danych a współczesnymi agentami AI.
Gdy programy komputerowe komunikują się ze sobą, przesyłanie informacji zwykłym, niestrukturalizowanym tekstem jest nieefektywne:
> *«Olena Kowalczuk, 29 lat, Kijów, subskrypcja premium aktywna, umiejętności: Python, SQL.»*
Człowiek łatwo zrozumie ten opis, ale algorytm zużyje znaczne zasoby na rozpoznanie encji. W formacie JSON te same dane wyglądają surowo i deterministycznie:
```json
{
"id": 1042,
"name": "Олена Ковальчук",
"age": 29,
"city": "Київ",
"isPremium": true,
"skills": ["Python", "SQL"]
}
```
Dowolny parser w dowolnym języku programowania (JavaScript, Python, Go, Rust) natychmiast odczyta klucz `"city"` i otrzyma wartość `"Kijów"` bez dwuznaczności.
```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)"]
```
### Dlaczego JSON nie zależy od JavaScript
Mimo swojej nazwy, JSON jest całkowicie niezależnym językowo formatem tekstowym. Posiada własny standard RFC (RFC 8259) i jest wspierany przez wszystkie współczesne ekosystemy dzięki standardowemu typowi MIME `application/json`.
---
## 2. Anatomia JSON: składnia obiektów, tablic i prymitywów
Wszystkie dane w formacie JSON opierają się na dwóch kluczowych kontenerach (obiektach i tablicach) oraz sześciu podstawowych typach wartości.
### Obiekt (JSON Object)
Obiekt reprezentuje nieuporządkowany zbiór par `klucz: wartość`, które muszą być ujęte w nawiasy klamrowe `{}`. Kluczem zawsze musi być ciąg znaków w podwójnych cudzysłowach.
```json
{
"username": "alex_dev",
"email": "alex@example.com",
"role": "admin"
}
```
### Tablica (JSON Array)
Tablica to uporządkowana lista wartości dowolnego typu, ujęta w nawiasy kwadratowe `[]`. Elementy tablicy indeksowane są od zera.
```json
{
"supportedLocales": ["uk", "en", "es", "de"],
"primeNumbers": [2, 3, 5, 7, 11]
}
```
### Dopuszczalne typy wartości (Values)
W JSON dozwolone jest używanie dokładnie 6 typów wartości:
| Typ wartości | Opis i zasady zapisu | Przykład |
| :--- | :--- | :--- |
| **String (Tekst)** | Ciąg znaków Unicode w podwójnych cudzysłowach | `"Hello, World!"` |
| **Number (Liczba)** | Liczba całkowita lub zmiennoprzecinkowa (bez cudzysłowów, bez heksadecymalnych) | `42`, `-12.5`, `1.5e3` |
| **Boolean (Logiczny)** | Tylko małe litery: `true` lub `false` | `true`, `false` |
| **Null** | Oznaczenie świadomego braku wartości | `null` |
| **Object (Obiekt)** | Zagnieżdżony kontener par klucz-wartość | `{"nested": true}` |
| **Array (Tablica)** | Zagnieżdżona lista elementów | `[1, 2, 3]` |
---
## 3. Surowe zasady składni i typowe pułapki
Składnia JSON jest znacznie bardziej rygorystyczna niż elastyczna składnia JavaScript czy Pythona. Błąd nawet w jednym znaku łamie walidację całego dokumentu.
### Pięć głównych zasad składni
1. **Tylko podwójne cudzysłowy:** Klucze i ciągi tekstowe muszą być ujęte w `"podwójne cudzysłowy"`. Pojedyncze cudzysłowy `'text'` powodują krytyczny błąd parsera.
2. **Brak wiszących przecinków (Trailing Commas):** Postawienie przecinka po ostatnim elemencie obiektu lub tablicy jest kategorycznie zabronione.
3. **Dwukropek jako jedyny separator:** Klucz oddzielony jest od wartości wyłącznie dwukropkiem `:`.
4. **Całkowity brak komentarzy:** Specyfikacja JSON nie obsługuje komentarzy `//` ani `/* */`. Wszelkie wyjaśnienia muszą być sformułowane jako zwykłe pola dokumentu (np. `"_comment": "Wyjaśnienie"`).
5. **Zabronione typy danych:** W JSON nie można przesyłać `undefined`, `NaN`, `Infinity`, wyrażeń regularnych ani funkcji.
### Porównanie poprawnego i niepoprawnego JSON
:::tabs
@tab Poprawny przykład
```json
{
"product": "MacBook Pro",
"price": 1999.99,
"inStock": true,
"tags": ["laptop", "apple", "m-series"]
}
```
@tab Niepoprawny przykład (Typowe błędy)
```json
{
product: 'MacBook Pro', // Помилка: одинарні лапки та ключ без лапок
"price": 1999.99,
"inStock": true,
"tags": ["laptop", "apple",], // Помилка: висяча кома
} // Помилка: висяча кома перед закриваючою дужкою
```
:::
---
## 4. Różnice między JSON a obiektami JavaScript
Początkujący często mylą literał obiektowy JavaScript z formatem JSON. Jednak istnieje między nimi fundamentalna różnica.
```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
```
### Tabela fundamentalnych różnic
| Cecha | Obiekt JavaScript | JSON (Format tekstowy) |
| :--- | :--- | :--- |
| **Forma istnienia** | Żywa struktura danych w pamięci operacyjnej | Ciąg znaków (sekwencja bajtów) |
| **Wymagania dotyczące kluczy** | Mogą być bez cudzysłowów lub Symbol | Koniecznie ciągi znaków w podwójnych cudzysłowach |
| **Obsługiwane typy** | Funkcje, metody, `Date`, `Map`, `Set`, `undefined` | Tylko 6 podstawowych typów (stringi, liczby, bool, null, obj, arr) |
| **Komentarze** | Dozwolone `//` oraz `/* */` | Całkowicie zabronione |
| **Wiszące przecinki** | Dozwolone przez współczesne standardy JS | Surowo zabronione przez standard |
---
## 5. Nawigacja i odczyt zagnieżdżonych struktur danych
W rzeczywistych projektach odpowiedzi API zawierają głębokie hierarchiczne struktury. Aby uzyskać dostęp do konkretnej wartości, stosuje się notację kropkową (`.`) dla obiektów oraz indeksy (`[]`) dla tablic.
### Przykład złożonego dokumentu
```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 }
]
}
```
### Ścieżki dostępu do elementów
- `order.orderId` $\rightarrow$ zwraca `"ORD-94821"`
- `order.customer.fullName` $\rightarrow$ zwraca `"Taras Szewczenko"`
- `order.customer.contacts.phones[0]` $\rightarrow$ zwraca pierwszy numer `"+380501112233"`
- `order.items[1].price` $\rightarrow$ zwraca cenę drugiego produktu `120`
> [!TIP]
> We współczesnym JavaScript, aby zapobiec błędom `TypeError: Cannot read properties of undefined`, zawsze używaj opcjonalnych łańcuchów (optional chaining): `order?.customer?.contacts?.email`.
---
## 6. JSON w REST API: żądania, odpowiedzi i nagłówki
Praktycznie wszystkie współczesne usługi webowe wykorzystują JSON jako protokół przesyłania ładunku użytkowego (Payload) przez protokół 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()
```
### Kluczowe nagłówki HTTP
1. **`Content-Type: application/json`:** wskazuje serwerowi lub klientowi, że w ciele żądania (Request Body) lub odpowiedzi (Response Body) przesyłany jest poprawny ciąg JSON.
2. **`Accept: application/json`:** klient informuje serwer, że oczekuje otrzymania odpowiedzi wyłącznie w formacie JSON (a nie XML czy HTML).
---
## 7. Serializacja i deserializacja: parse i stringify
Konwersja żywych obiektów z pamięci na tekst nazywa się **serializacją** (*Serialization*), a odwrotna konwersja tekstu na obiekt — **deserializacją** (*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. Diagnostyka błędów składni i walidacja
Jeśli tekst zawiera choćby jeden błąd składniowy, wywołanie `JSON.parse()` rzuca wyjątek `SyntaxError`, co może awaryjnie zatrzymać działanie aplikacji.
```javascript
try {
const data = JSON.parse(untrustedUserInput);
} catch (error) {
console.error("Невалідний JSON:", error.message);
}
```
### Lista kontrolna szybkiej diagnostyki
- [ ] Czy wszystkie nawiasy klamrowe `{}` oraz kwadratowe `[]` są zamknięte?
- [ ] Czy wszystkie klucze są ujęte właśnie w podwójne cudzysłowy `""`?
- [ ] Czy nie ma wiszącego przecinka przed ostatnim nawiasem?
- [ ] Czy do tekstu nie dostały się wartości `undefined`, `NaN` lub komentarze?
- [ ] Czy wewnętrzne cudzysłowy w stringach są escapowane: `"quote": "Słowo \"w cudzysłowach\""`?
---
## 9. JSON Schema: sprawdzanie kontraktów i struktury
Poprawność składniowa JSON nie gwarantuje jeszcze, że dane mają właściwą strukturę biznesową. Jeśli API oczekuje liczby `age`, a otrzymuje string `"dwadzieścia"`, program padnie na etapie obliczeń.
Do formalnego opisu wymagań dotyczących struktury wykorzystywany jest standard **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"]
}
```
Dowolny walidator (np. Ajv w JavaScript lub jsonschema w Pythonie) automatycznie sprawdzi dane wejściowe według tego kontraktu jeszcze przed przekazaniem ich do bazy danych.
---
## 10. Dane strukturalne dla LLM, wywołań funkcji i agentów AI
We współczesnej rozwoju sztucznej inteligencji odpowiedzi tekstowe w swobodnym formacie stopniowo ustępują miejsca **Structured Outputs**.
Agenci AI (np. Claude Code, OpenAI Function Calling, LangChain) wykorzystują JSON do wywoływania zewnętrznych narzędzi:
```json
{
"name": "sendEmailNotification",
"arguments": {
"recipient": "user@example.com",
"subject": "Рахунок сформовано",
"invoiceId": "INV-2026-09"
}
}
```
### Jak zagwarantować zwrot czystego JSON przez model językowy
1. **Podaj schemat w prompcie systemowym:** Zawsze przekazuj dokładny model TypeScript lub JSON Schema.
2. **Żądaj surowego wyjścia:** Używaj instrukcji: *"Return ONLY a valid raw JSON object. Do not wrap in markdown code blocks or add introductory text."*
3. **Używaj trybu Structured Outputs:** U dostawców API (Anthropic Tool Use / OpenAI JSON Mode) włączaj wymuszoną walidację schematu na poziomie generatora tokenów.
---
## 11. Porównanie formatów: JSON, YAML, XML i TOML
| Format | Czytelność dla człowieka | Obsługa komentarzy | Objętość znaczników | Główna dziedzina zastosowań |
| :--- | :--- | :--- | :--- | :--- |
| **JSON** | Średnia / Wysoka | Nie | Minimalna | Web API, komunikacja klient-serwer, wywołania AI |
| **YAML** | Bardzo wysoka | Tak | Zerowa (wcięcia) | Konfiguracje CI/CD (GitHub Actions, K8s) |
| **TOML** | Bardzo wysoka | Tak | Niska | Konfiguracje projektów (Cargo, pyproject.toml) |
| **XML** | Niska | Tak | Wysoka (tagi) | Legacy systemy enterprise, SOAP, SVG |
---
## 12. Praktyczny warsztat, samoocena i podsumowująca lista kontrolna
Utrwalmy wszystkie zdobyte umiejętności na pełnym cyklu: od pobrania danych z API po walidację i odczyt.
### Pełny scenariusz pobierania i odczytu danych
```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);
}
}
```
### Szybka samoocena
> **1. Jaki błąd wystąpi, jeśli w pliku JSON użyjesz pojedynczych cudzysłowów dla stringa?**
>
> > [!TIP]
> > **Odpowiedź:** Wystąpi błąd parsowania `SyntaxError: Unexpected token ' in JSON`. Specyfikacja JSON pozwala wyłącznie na podwójne cudzysłowy `""`.
> **2. Dlaczego po ostatnim elemencie w obiekcie JSON nie można postawić przecinka?**
>
> > [!TIP]
> > **Odpowiedź:** Standard JSON zabrania wiszących przecinków (trailing commas). Parser oczekuje po przecinku następnej pary klucz-wartość, a jeśli napotka zamykający nawias `}`, powstaje krytyczny błąd składni.
> **3. Do czego potrzebny jest standard JSON Schema?**
>
> > [!TIP]
> > **Odpowiedź:** Aby sprawdzać strukturę biznesową i typy danych w dokumencie (obecność wymaganych pól, minimalne wartości liczb, format email), a nie tylko podstawową poprawność składniową.
### Podsumowująca lista kontrolna pracy z JSON
- [ ] Wszystkie stringi i klucze sformatowano w podwójnych cudzysłowach `""`.
- [ ] Sprawdzono brak wiszących przecinków przed `}` oraz `]`.
- [ ] Usunięto wszystkie komentarze z dokumentu.