# JSON — données structurées pour les applications, les API et les agents IA
> Guide pratique complet du format JSON : règles de syntaxe, sérialisation via parse/stringify, intégration avec les API REST, schémas JSON et sortie structurée pour l'intelligence artificielle.
## 1. Qu'est-ce que le JSON et pourquoi est-il devenu un standard
Le format **JSON** (*JavaScript Object Notation*) est un standard universel pour l'échange de données structurées entre serveurs web, applications clientes, bases de données et agents IA modernes.
Lorsque les programmes informatiques interagissent entre eux, transmettre des informations sous forme de texte brut non structuré est inefficace :
> *« Olena Kovalchuk, 29 ans, Kyiv, abonnement premium actif, compétences : Python, SQL. »*
Un humain comprendra facilement cette description, mais un algorithme dépensera des ressources considérables pour la reconnaissance d'entités. Au format JSON, ces mêmes données sont strictes et déterministes :
```json
{
"id": 1042,
"name": "Олена Ковальчук",
"age": 29,
"city": "Київ",
"isPremium": true,
"skills": ["Python", "SQL"]
}
```
N'importe quel parser dans n'importe quel langage de programmation (JavaScript, Python, Go, Rust) lira instantanément la clé `"city"` et récupérera la valeur `"Kyiv"` sans aucune ambiguïté.
```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)"]
```
### Pourquoi JSON ne dépend pas de JavaScript
Malgré son nom, JSON est un format textuel totalement indépendant du langage. Il possède sa propre norme RFC (RFC 8259) et est pris en charge par tous les écosystèmes modernes via le type MIME standard `application/json`.
---
## 2. Anatomie du JSON : syntaxe des objets, tableaux et primitives
Toutes les données au format JSON s'articulent autour de deux conteneurs clés (objets et tableaux) et six types de valeurs fondamentaux.
### Objet (JSON Object)
Un objet représente une collection non ordonnée de paires `clé: valeur`, obligatoirement encadrées par des accolades `{}`. La clé doit toujours être une chaîne de caractères entre guillemets doubles.
```json
{
"username": "alex_dev",
"email": "alex@example.com",
"role": "admin"
}
```
### Tableau (JSON Array)
Un tableau est une liste ordonnée de valeurs de tout type, encadrée par des crochets `[]`. Les éléments du tableau sont indexés à partir de zéro.
```json
{
"supportedLocales": ["uk", "en", "es", "de"],
"primeNumbers": [2, 3, 5, 7, 11]
}
```
### Types de valeurs autorisés (Values)
Le JSON autorise exactement 6 types de valeurs :
| Type de valeur | Description et règles d'écriture | Exemple |
| :--- | :--- | :--- |
| **Chaîne (String)** | Séquence de caractères Unicode entre guillemets doubles | `"Hello, World!"` |
| **Nombre (Number)** | Nombre entier ou décimal (sans guillemets, sans hexadécimal) | `42`, `-12.5`, `1.5e3` |
| **Booléen (Boolean)** | Uniquement en minuscules : `true` ou `false` | `true`, `false` |
| **Null** | Indication d'une absence volontaire de valeur | `null` |
| **Objet (Object)** | Conteneur imbriqué de paires clé-valeur | `{"nested": true}` |
| **Tableau (Array)** | Liste imbriquée d'éléments | `[1, 2, 3]` |
---
## 3. Règles strictes de syntaxe et pièges courants
La syntaxe JSON est beaucoup plus stricte que celle, flexible, de JavaScript ou Python. Une erreur sur un seul caractère invalide la validation de tout le document.
### Les cinq règles principales de la syntaxe
1. **Guillemets doubles uniquement :** Les clés et les chaînes de caractères doivent impérativement être entourées de `"guillemets doubles"`. Les guillemets simples `'text'` provoquent une erreur fatale du parser.
2. **Aucune virgule traînante (Trailing Commas) :** Il est catégoriquement interdit de placer une virgule après le dernier élément d'un objet ou d'un tableau.
3. **Deux-points comme unique séparateur :** La clé est séparée de la valeur exclusivement par deux-points `:`.
4. **Absence totale de commentaires :** La spécification JSON ne prend pas en charge les commentaires `//` ni `/* */`. Toute explication doit être intégrée comme un champ standard du document (par exemple, `"_comment": "Explication"`).
5. **Types de données interdits :** Le JSON ne permet pas de transmettre `undefined`, `NaN`, `Infinity`, des expressions régulières ou des fonctions.
### Comparaison entre JSON valide et invalide
:::tabs
@tab Exemple valide
```json
{
"product": "MacBook Pro",
"price": 1999.99,
"inStock": true,
"tags": ["laptop", "apple", "m-series"]
}
```
@tab Exemple invalide (Erreurs courantes)
```json
{
product: 'MacBook Pro', // Помилка: одинарні лапки та ключ без лапок
"price": 1999.99,
"inStock": true,
"tags": ["laptop", "apple",], // Помилка: висяча кома
} // Помилка: висяча кома перед закриваючою дужкою
```
:::
---
## 4. Différences entre JSON et les objets JavaScript
Les débutants confondent souvent le littéral d'objet JavaScript avec le format JSON. Pourtant, il existe une différence fondamentale entre les deux.
```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
```
### Tableau des différences fondamentales
| Caractéristique | Objet JavaScript | JSON (Format textuel) |
| :--- | :--- | :--- |
| **Forme d'existence** | Structure de données vivante en mémoire vive | Chaîne de caractères (séquence d'octets) |
| **Exigences pour les clés** | Peuvent être sans guillemets ou de type Symbol | Obligatoirement des chaînes entre guillemets doubles |
| **Types supportés** | Fonctions, méthodes, `Date`, `Map`, `Set`, `undefined` | Seulement 6 types de base (chaînes, nombres, bool, null, obj, arr) |
| **Commentaires** | Autorisés `//` et `/* */` | Totalement interdits |
| **Virgules traînantes** | Autorisées par les standards JS modernes | Strictement interdites par la norme |
---
## 5. Navigation et lecture de structures de données imbriquées
Dans les projets réels, les réponses API contiennent des hiérarchies profondes. Pour accéder à une valeur spécifique, on utilise la notation pointée (`.`) pour les objets et les indices (`[]`) pour les tableaux.
### Exemple de document complexe
```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 }
]
}
```
### Chemins d'accès aux éléments
- `order.orderId` $\rightarrow$ renvoie `"ORD-94821"`
- `order.customer.fullName` $\rightarrow$ renvoie `"Taras Shevchenko"`
- `order.customer.contacts.phones[0]` $\rightarrow$ renvoie le premier numéro `"+380501112233"`
- `order.items[1].price` $\rightarrow$ renvoie le prix du deuxième article `120`
> [!TIP]
> En JavaScript moderne, pour éviter les erreurs `TypeError: Cannot read properties of undefined`, utilisez toujours les chaînages optionnels : `order?.customer?.contacts?.email`.
---
## 6. JSON dans les REST API : requêtes, réponses et en-têtes
Pratiquement tous les services web modernes utilisent JSON comme protocole de transfert de charge utile (Payload) via 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()
```
### En-têtes HTTP clés
1. **`Content-Type: application/json` :** Indique au serveur ou au client que le corps de la requête (Request Body) ou de la réponse (Response Body) contient une chaîne JSON valide.
2. **`Accept: application/json` :** Le client informe le serveur qu'il attend une réponse exclusivement au format JSON (et non XML ou HTML).
---
## 7. Sérialisation et désérialisation : parse et stringify
La conversion d'objets vivants en mémoire vers du texte s'appelle la **sérialisation** (*Serialization*), tandis que la conversion inverse du texte vers un objet est la **désérialisation** (*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. Diagnostic des erreurs de syntaxe et validation
Si le texte contient ne serait-ce qu'une seule erreur de syntaxe, l'appel `JSON.parse()` lève une exception `SyntaxError`, ce qui peut interrompre brutalement le fonctionnement de l'application.
```javascript
try {
const data = JSON.parse(untrustedUserInput);
} catch (error) {
console.error("Невалідний JSON:", error.message);
}
```
### Checklist de diagnostic rapide
- [ ] Toutes les accolades `{}` et crochets `[]` sont-ils fermés ?
- [ ] Toutes les clés sont-elles bien entre guillemets doubles `""` ?
- [ ] Y a-t-il une virgule traînante avant la dernière parenthèse ?
- [ ] Des valeurs `undefined`, `NaN` ou des commentaires se sont-ils glissés dans le texte ?
- [ ] Les guillemets internes dans les chaînes sont-ils échappés : `"quote": "Mot \"entre guillemets\""` ?
---
## 9. JSON Schema : vérification des contrats et de la structure
Un JSON syntaxiquement correct ne garantit pas que les données respectent la bonne structure métier. Si une API attend un nombre `age` et reçoit la chaîne `"vingt"`, le programme plantera lors des calculs.
Pour décrire formellement les exigences structurelles, on utilise le 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"]
}
```
N'importe quel validateur (comme Ajv en JavaScript ou jsonschema en Python) vérifiera automatiquement les données entrantes selon ce contrat avant leur insertion en base de données.
---
## 10. Données structurées pour les LLM, les appels de fonction et les agents IA
Dans le développement moderne lié à l'intelligence artificielle, les réponses textuelles libres cèdent progressivement la place aux **Structured Outputs**.
Les agents IA (comme Claude Code, OpenAI Function Calling, LangChain) utilisent JSON pour appeler des outils externes :
```json
{
"name": "sendEmailNotification",
"arguments": {
"recipient": "user@example.com",
"subject": "Рахунок сформовано",
"invoiceId": "INV-2026-09"
}
}
```
### Comment garantir le retour d'un JSON pur par un modèle de langage
1. **Indiquez le schéma dans le prompt système :** Transmettez toujours un modèle TypeScript exact ou un JSON Schema.
2. **Exigez une sortie brute :** Utilisez l'instruction : *"Return ONLY a valid raw JSON object. Do not wrap in markdown code blocks or add introductory text."*
3. **Utilisez le mode Structured Outputs :** Chez les fournisseurs d'API (Anthropic Tool Use / OpenAI JSON Mode), activez la validation de schéma forcée au niveau du générateur de tokens.
---
## 11. Comparaison des formats : JSON, YAML, XML et TOML
| Format | Lisibilité humaine | Support des commentaires | Volume de balisage | Domaine d'application principal |
| :--- | :--- | :--- | :--- | :--- |
| **JSON** | Moyenne / Élevée | Non | Minimal | Web API, communication client-serveur, appels IA |
| **YAML** | Très élevée | Oui | Nul (indentation) | Configurations CI/CD (GitHub Actions, K8s) |
| **TOML** | Très élevée | Oui | Faible | Configurations de projets (Cargo, pyproject.toml) |
| **XML** | Faible | Oui | Élevé (balises) | Systèmes enterprise hérités, SOAP, SVG |
---
## 12. Atelier pratique, auto-évaluation et checklist finale
Consolidons toutes les compétences acquises sur un cycle complet : de la récupération des données API à la validation et la lecture.
### Scénario complet de récupération et lecture de données
```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);
}
}
```
### Auto-évaluation rapide
> **1. Quelle erreur surviendra si vous utilisez des guillemets simples pour une chaîne dans un fichier JSON ?**
>
> > [!TIP]
> > **Réponse :** Une erreur de parsing `SyntaxError: Unexpected token ' in JSON` se produira. La spécification JSON autorise exclusivement les guillemets doubles `""`.
> **2. Pourquoi ne peut-on pas mettre de virgule après le dernier élément d'un objet JSON ?**
>
> > [!TIP]
> > **Réponse :** Le standard JSON interdit les virgules traînantes (trailing commas). Le parser attend une nouvelle paire clé-valeur après la virgule ; s'il trouve une parenthèse fermante `}`, cela provoque une erreur de syntaxe fatale.
> **3. À quoi sert le standard JSON Schema ?**
>
> > [!TIP]
> > **Réponse :** À vérifier la structure métier et les types de données dans le document (présence de champs obligatoires, valeurs minimales numériques, format email), et non seulement la validité syntaxique de base.
### Checklist finale pour travailler avec JSON
- [ ] Toutes les chaînes et clés sont rédigées entre guillemets doubles `""`.
- [ ] L'absence de virgules traînantes avant `}` et `]` a été vérifiée.
- [ ] Tous les commentaires ont été retirés du document.