Skip to content

JSON Aide-mémoire

Format léger d'échange de données pour l'échange d'informations.

01

Démarrage

Structure de base

JSON gère 6 types de données : string, number, boolean, null, array et object. Les clés doivent être des chaînes entre guillemets doubles. JSON est indépendant des langages et facile à lire pour les humains comme pour les machines.

json
{
  "name": "Alice",
  "age": 30,
  "isStudent": false,
  "height": 1.65,
  "nullValue": null,
  "hobbies": ["reading", "coding", "music"],
  "address": {
    "city": "NYC",
    "zip": "10001"
  }
}

Règles de syntaxe JSON

JSON a une syntaxe stricte : clés et chaînes en guillemets doubles uniquement, virgules entre les éléments, virgules finales interdites. Le document entier doit être une unique valeur JSON. Le JSON standard n'accepte pas de commentaires — servez-vous d'un préprocesseur ou de JSON5 si besoin.

json
{
  "key": "value",          // key MUST be a double-quoted string
  "nested": { "a": 1 },    // objects use { } with comma-separated pairs
  "list": [1, 2, 3]        // arrays use [ ] with comma-separated values
}

// Rules:
// - Double quotes only for strings and keys (no single quotes)
// - Comma separates members; NO trailing comma
// - The whole document is ONE value (usually an object or array)
// - No comments allowed in standard JSON

Commentaires dans JSON

Le JSON standard interdit les commentaires. Parades courantes : ajouter un champ '_comment' (ignoré par le code), utiliser JSONC/JSON5 (pris en charge par VS Code et bien des outils), ou retirer les commentaires avant parsing avec une bibliothèque comme comment-json ou JSON.minify.

json
// Standard JSON does NOT allow comments.

// Workaround 1: include a descriptive field
{
  "_comment": "This is a config file for the app",
  "port": 8080
}

// Workaround 2: use JSON5 or JSONC (VS Code settings)
{
  // line comment
  "port": 8080 /* block comment */
}

// Workaround 3: strip comments before parsing
// (e.g., JSON.minify, comment-json npm package)

Espaces et mise en forme

Les espaces hors chaînes ne comptent pas — les formes compacte et indentée parsent vers la même valeur. Le JSON compact économise la bande passante ; le pretty-print (indentation de 2 espaces courante) aide la lisibilité et les diffs. La plupart des sérialiseurs offrent une option 'pretty'.

json
// These are all equivalent:

{"a":1,"b":2}                       // compact (no whitespace)

{ "a": 1, "b": 2 }                  // readable

{
  "a": 1,
  "b": 2
}                                   // pretty-printed

// Whitespace between tokens is insignificant.
// Use compact for transmission, pretty for humans.

Extension de fichier et type MIME

L'extension de fichier standard est .json et le type MIME est application/json. Les variantes comme JSONC, JSON5, GeoJSON et NDJSON ont leurs propres conventions. Employez toujours l'encodage UTF-8 ; le BOM est déconseillé.

json
// File extensions:
//   .json    standard JSON
//   .jsonc   JSON with comments (VS Code, TypeScript config)
//   .json5   JSON5 (relaxed syntax)
//   .geojson GeoJSON (geographic data)
//   .ndjson  Newline-Delimited JSON (JSON Lines)
//   .har     HTTP Archive (JSON-based)

// MIME type:
Content-Type: application/json

// Older/alternate MIME types (avoid):
//   text/json          (non-standard)
//   application/x-json (non-standard)

// UTF-8 is the default and recommended encoding.

Catégories de valeurs JSON

Les valeurs JSON se répartissent en six types : string, number, boolean, null, array, object. Les arrays et objects sont structurés (peuvent porter d'autres valeurs) ; le reste est primitif. Un document JSON valide est une valeur — couramment un objet ou un tableau, mais un nombre ou une chaîne nue est aussi valide.

json
// A JSON value is exactly one of these six types:

"hello"                 // string
42                      // number
3.14                    // number
true                    // boolean
false                   // boolean
null                    // null
[1, 2, 3]               // array
{ "a": 1 }              // object

// Structured types: array, object
// Primitive types: string, number, boolean, null
// A standalone JSON document is a single value of any type.
02

Types de données

Type string

Les chaînes JSON sont du texte Unicode entre guillemets doubles. Échappements courants : \" (guillemet), \\ (backslash), \/ (slash), \n, \t, \r, \b, \f, et \uXXXX pour n'importe quel point de code Unicode. Les guillemets simples ne sont pas admis comme délimiteurs de chaîne.

json
{
  "single": "double quotes only",
  "empty": "",
  "escaped": "He said \"hi\" and C:\\Users",
  "unicode": "Cafu00e9 \u00e9 \u1F600",
  "multiline": "line1\nline2\ttabbed"
}

// Strings MUST use double quotes.
// Single quotes are NOT valid in JSON.

Type number

Les nombres JSON suivent un sous-ensemble du double IEEE 754 : entiers, décimaux et notation scientifique (ex. 6.022e23). Les zéros initiaux sont interdits (007 est invalide). NaN, Infinity et -Infinity ne sont PAS valides — encodez-les en null ou chaînes si besoin.

json
{
  "integer": 42,
  "negative": -7,
  "float": 3.14,
  "zero": 0,
  "scientific": 6.022e23,
  "small": 1.5e-10
}

// Numbers are NOT quoted.
// No leading zeros (007 is invalid).
// No NaN, Infinity, or -Infinity (not valid JSON).

Type boolean

Les booléens JSON sont les mots-clés littéraux true et false (minuscules, sans guillemets). Les 'true'/'false' cités sont des chaînes. JSON n'a pas de notion de 0/1 ni oui/non comme booléens — convertissez-les dans votre code applicatif.

json
{
  "enabled": true,
  "disabled": false,
  "flag": true
}

// Booleans are the bare keywords true and false.
// They are NOT quoted ("true" is a string).
// 0/1, yes/no, on/off are NOT booleans in JSON.

Type null

Le null JSON est le mot-clé nu null (sans guillemets). Il signale l'absence volontaire d'une valeur. Notez que null se distingue de la chaîne vide '', de 0, de false ou d'une clé manquante. Beaucoup de langages mappent null vers None/nil/null.

json
{
  "middleName": null,
  "deletedAt": null,
  "optional": null
}

// null is a bare keyword (unquoted).
// "null" (quoted) is a string, not null.
// null represents the intentional absence of value.

Type array

Les tableaux JSON sont des listes ordonnées enveloppées dans [ ], séparées par des virgules, indexées à partir de zéro. Ils peuvent porter toute valeur JSON, y compris des types mixtes et des tableaux/objets imbriqués. Les tableaux vides [] sont valides. L'ordre est préservé et significatif.

json
{
  "numbers": [1, 2, 3],
  "mixed": [1, "two", true, null],
  "nested": [[1, 2], [3, 4]],
  "objects": [
    { "id": 1 },
    { "id": 2 }
  ],
  "empty": []
}

// Arrays are ordered, zero-indexed, and can hold mixed types.

Type object

Les objets JSON sont des collections clé/valeur non ordonnées enveloppées dans { }. Les clés doivent être des chaînes uniques entre guillemets doubles ; les valeurs peuvent être de tout type JSON. Bien que conceptuellement non ordonnés, la plupart des parseurs conservent l'ordre d'insertion ; n'en dépendez pas pour la correction.

json
{
  "user": {
    "id": 1,
    "name": "Alice",
    "roles": ["admin", "user"],
    "active": true
  },
  "empty": {}
}

// Objects are unordered collections of key/value pairs.
// Keys MUST be unique strings (double-quoted).
// Values can be any JSON type.
03

Chaînes

Bases des chaînes

Les chaînes JSON sont des séquences de caractères Unicode entre guillemets doubles. Le slash peut être échappé (\/) mais sans obligation — utile quand on intègre du JSON dans des balises <script>. Les chaînes vides sont valides.

json
{
  "name": "Alice",
  "email": "[email protected]",
  "url": "https://example.com/path?q=1",
  "path": "C:\\Users\\alice",
  "empty": ""
}

// Strings are double-quoted Unicode text.
// Forward slash may be escaped as \/ but does not have to be.

Séquences d'échappement

JSON gère ces échappements : \" (guillemet), \\ (backslash), \/ (slash), \b (retour arrière), \f (saut de page), \n (nouvelle ligne), \r (retour chariot), \t (tabulation), et \uXXXX (point de code Unicode). Toute autre séquence avec backslash est invalide.

json
{
  "quote": "She said \"hello\"",
  "backslash": "C:\\Users\\name",
  "newline": "line1\nline2",
  "tab": "col1\tcol2",
  "carriage": "a\rb",
  "backspace": "a\bb",
  "formfeed": "a\fb",
  "slash": "a\/b"
}

// Valid escapes: \" \\ \/ \b \f \n \r \t \uXXXX

Caractères Unicode

Employez \uXXXX pour n'importe quel point de code Unicode. Les caractères au-dessus de U+FFFF (comme bien des emoji) exigent une paire surrogate : deux échappements \u. Les parseurs modernes acceptent aussi le caractère UTF-8 brut directement dans la chaîne — \uXXXX sert surtout par sécurité ou quand on ne peut taper le caractère.

json
{
  "eacute": "Caf\u00e9",
  "euro": "Price: \u20ac10",
  "emoji": "Smile \ud83d\ude00",
  "chinese": "\u4f60\u597d",
  "raw": "Cafu00e9 u00e9 \u00e9"
}

// \uXXXX encodes a code point in the Basic Multilingual Plane.
// Surrogate pairs (two \u escapes) encode characters above U+FFFF.
// Modern parsers also accept the raw UTF-8 character directly.

Caractères spéciaux dans les chaînes

Dans une chaîne JSON, le guillemet double et le backslash doivent toujours être échappés (\" et \\). Les autres caractères spéciaux (HTML, SQL, regex) suivent leurs propres règles, mais JSON n'exige que l'échappement de \" et \\ (plus les caractères de contrôle). Un backslash littéral s'écrit \\.

json
{
  "html": "<div class=\"x\">Hi</div>",
  "sql": "SELECT * FROM t WHERE name='O''Brien'",
  "regex": "^\\d{3}-\\d{4}$",
  "json": "{ \"k\": \"v\" }",
  "cmd": "echo \"hello\""
}

// Backslash is the universal escape character.
// To include a literal backslash, write \\.

Chaînes multi-lignes (contournement)

Les chaînes JSON ne peuvent contenir de sauts de ligne littéraux — il faut les échapper en \n. Pour du contenu multi-lignes, insérez \n dans la chaîne, employez un tableau de chaînes de lignes, ou passez à un format comme YAML ou JSON5 qui gère les chaînes multi-lignes. Les sauts de ligne bruts non échappés sont une erreur de syntaxe.

json
// JSON does NOT support real multi-line strings.
// The following is INVALID:
// { "text": "line1
// line2" }

// Workaround 1: escape the newline
{ "text": "line1\nline2" }

// Workaround 2: array of lines
{ "lines": ["line1", "line2"] }

// Workaround 3: JSON5 allows continued strings (still single logical line)

Pièges courants des chaînes

Erreurs de chaîne courantes : employer des guillemets simples, laisser une virgule finale, oublier d'échapper les guillemets doubles internes, et insérer des caractères de contrôle littéraux (tabulation/saut de ligne) au lieu de leurs échappements \t/\n. Un parseur strict rejette tout cela.

json
// WRONG: single quotes
// { 'name': 'Alice' }

// WRONG: trailing comma
// { "a": 1, }

// WRONG: unescaped quote
// { "msg": "He said "hi"" }

// WRONG: literal tab/newline in string
// { "x": "a<TAB>b" }

// RIGHT:
{ "name": "Alice", "msg": "He said \"hi\"" }
04

Nombres

Entier et flottant

JSON n'a qu'un seul type number qui couvre entiers et valeurs flottantes. Pas de type entier séparé au niveau syntaxe — les liaisons de langage peuvent mapper les grands entiers vers int, long, float ou decimal selon la valeur et la bibliothèque.

json
{
  "count": 100,
  "negative": -42,
  "temperature": -273.15,
  "pi": 3.14159,
  "zero": 0,
  "negativeZero": -0
}

// Integers and floats use the same number type.
// JSON does not distinguish int from float at the syntax level.

Notation scientifique

JSON gère la notation scientifique : une mantisse suivie de e ou E et d'un exposant signé optionnel (6.022e23 = 6.022 * 10^23). e et E sont acceptés tous deux. Essentiel pour les très grands ou très petits nombres des données scientifiques.

json
{
  "avogadro": 6.022e23,
  "planck": 6.626e-34,
  "speedOfLight": 2.998e8,
  "small": 1.5E-10
}

// e or E is allowed (case-insensitive).
// 6.022e23 means 6.022 * 10^23.
// The exponent may be negative.

Précision des nombres

Les nombres JSON se parsent typiquement en doubles IEEE 754, donc les entiers au-dessus de 2^53-1 (9007199254740991) perdent de la précision en JavaScript. Les décimaux comme 0.1 ne se représentent pas exactement. Pour l'argent ou les entiers à précision arbitraire, encodez-les en chaînes et employez un type Decimal/BigInteger dans votre code.

json
{
  "big": 9007199254740993,
  "decimal": 0.1,
  "sum": 0.1,
  "money": 19.99
}

// JavaScript stores numbers as IEEE 754 doubles.
// Integers are safe up to 2^53 - 1 (9007199254740991).
// 0.1 + 0.2 === 0.30000000000000004 (float precision loss).

// For money or big integers, parse as string or use a Decimal type.

Valeurs spéciales (interdites)

Le JSON standard n'admet pas NaN, Infinity ni -Infinity. Parades : null pour NaN, Infinity encodé en chaîne, ou une valeur sentinelle finie. Certains sérialiseurs (le json de Python par défaut, JSON5) les émettent comme extensions, mais la sortie est non standard et peut être rejetée par des parseurs stricts.

json
// NaN, Infinity, and -Infinity are NOT valid JSON.

// INVALID:
// { "x": NaN }
// { "y": Infinity }
// { "z": -Infinity }

// Common workarounds:
{
  "x": null,           // represent NaN/null
  "y": "Infinity",     // encode as a string
  "z": 1.7976931348623157e308  // use a finite max
}

// Many serializers (e.g., Python json) accept these as extensions
// but the output is not standard JSON.

Formats de nombres

Nombres JSON valides : moins optionnel, partie entière (pas de zéros initiaux sauf pour 0), partie fractionnaire optionnelle, exposant optionnel. Hexa (0x), binaire (0b), octal, underscores, + initial, zéros initiaux et point sans chiffres des deux côtés sont tous invalides.

json
// VALID JSON numbers:
42
-7
0
3.14
-0.5
6.022e23
1.5E-10
100.00

// INVALID:
007        // leading zero
.5         // no leading digit
5.         // no trailing digit after dot
+5         // leading plus sign
0x1F       // hex
0b101      // binary
1_000      // underscores

Grands nombres et BigInt

Pour les valeurs au-dessus de 2^53-1 (ex. IDs snowflake de Twitter, entiers 64 bits, grands soldes), encodez-les en chaînes pour éviter la perte de précision. Si vous devez employer un reviver dans JSON.parse pour convertir en BigInt, rappelez-vous que BigInt ne se re-sérialise pas par JSON.stringify sans replacer — les chaînes sont plus sûres sur le fil.

json
{
  "snowflake": "1234567890123456789",
  "timestamp": 1696000000000,
  "balance": "99999999999999999999"
}

// Numbers above 2^53-1 lose precision in JS.
// Use STRINGS for IDs, snowflakes, and big integers.

// In JavaScript, parse with a reviver:
// JSON.parse(str, (k, v) =>
//   typeof v === "number" && v > Number.MAX_SAFE_INTEGER
//     ? BigInt(v) : v);  // careful: BigInt can't be in JSON.stringify

// Better: keep them as strings on the wire.
05

Booléens et null

Valeurs booléennes

Les booléens JSON sont les mots-clés nus true et false. Les 'true'/'false' cités sont des chaînes. JSON n'a pas de notion de truthy/falsy au niveau syntaxe — 1, 0, yes, no, on, off sont tous des chaînes ou des nombres, pas des booléens. Convertissez-les dans le code applicatif.

json
{
  "enabled": true,
  "disabled": false,
  "isPublic": true,
  "isActive": false
}

// Only two boolean values: true and false (lowercase, unquoted).
// "true" (quoted) is a STRING, not a boolean.
// 1/0, yes/no, on/off are NOT booleans.

Signification de null

Le null JSON signale l'absence volontaire d'une valeur. Il se distingue d'une clé manquante (clé absente de l'objet), d'une chaîne vide '', de 0, de false ou d'une collection vide. Employez null quand un champ existe mais n'a pas de valeur ; omettez la clé quand le champ ne s'applique pas.

json
{
  "middleName": null,
  "deletedAt": null,
  "parent": null,
  "optional": null
}

// null means "no value" or "intentionally absent".
// Distinct from:
//   - missing key (key not present at all)
//   - empty string ""
//   - 0 or false
//   - empty array [] or object {}

Null vs vide vs absent

Trois états distincts : une clé avec valeur vide (""), une clé explicitement null, et une clé manquante. En JavaScript, undefined signifie que la clé est absente tandis que null signifie qu'elle est présente mais sans valeur. Les API devraient documenter la convention employée pour les champs optionnels.

json
{
  "name": "Alice",
  "nickname": "",          // empty string (present, empty)
  "middleName": null,      // explicit null (present, no value)
  // "maidenName"           // missing (key not in object)
}

// In JavaScript:
//   obj.nickname === ""           // true
//   obj.middleName === null       // true
//   obj.maidenName === undefined  // true (key absent)
//   "maidenName" in obj           // false

// Choose deliberately: null vs "" vs missing.

Employer les booléens dans les conditions

En consommant des booléens JSON, préférez la comparaison stricte (=== true) aux vérifications truthy si vous devez distinguer false d'absent. Dans les réponses d'API, incluez toujours les champs booléens même à false — les omettre force les clients à deviner le défaut.

json
{
  "isAdmin": true,
  "canEdit": false,
  "active": true
}

// In application code (JavaScript):
// if (user.isAdmin) { ... }       // truthy check
// const canEdit = user.canEdit === true;  // strict boolean check

// Be careful: a missing 'canEdit' key is undefined (falsy),
// but explicit false is also falsy. Distinguish if needed.

// API design: always send the boolean, even when false.

Pièges courants

Pièges courants : citer true/false/null en fait des chaînes ; employer True/TRUE/None (Python) ou true/false avec la mauvaise casse est invalide ; JSON n'a pas d'undefined (seulement null). Les seules formes valides sont les mots-clés minuscules sans guillemets true, false et null.

json
// Pitfall 1: quoting booleans/null
// { "x": "true" }   -> x is a STRING, not a boolean
// { "y": "null" }   -> y is a STRING, not null

// Pitfall 2: wrong case
// { "x": True }     -> INVALID (Python-style, not JSON)
// { "x": TRUE }     -> INVALID
// { "x": None }     -> INVALID

// Pitfall 3: confusing null with undefined
//   null exists in JSON; undefined does NOT.

// Correct:
{ "x": true, "y": null }
06

Tableaux

Bases des tableaux

Les tableaux JSON sont des listes ordonnées, indexées à partir de zéro, enveloppées dans [ ], avec des valeurs séparées par des virgules. Tableaux vides et tableaux à un élément sont valides. L'ordre est significatif et préservé par les parseurs. Pas de virgule finale admise.

json
{
  "numbers": [1, 2, 3, 4, 5],
  "strings": ["a", "b", "c"],
  "booleans": [true, false, true],
  "empty": [],
  "single": [42]
}

// Arrays are ordered, zero-indexed lists in [ ].
// Elements are separated by commas (no trailing comma).
// Empty arrays [] and single-element arrays are valid.

Tableaux à types mixtes

Les tableaux JSON peuvent légalement porter des types mixtes ([1, 'two', true, null]). C'est valide mais signale souvent un schéma faible. Les tableaux homogènes (tout chaînes, tout objets) sont plus faciles à valider, documenter et consommer. Employez un schéma pour imposer les types d'éléments.

json
{
  "mixed": [1, "two", true, null, 3.14],
  "nested": [[1, 2], "x", { "a": 1 }]
}

// JSON arrays CAN hold values of different types.
// This is valid but often a sign of weak schema design.
// Prefer homogeneous arrays for clarity and validation.

Tableaux imbriqués

Les tableaux peuvent s'imbriquer à toute profondeur, utile pour matrices, grilles et arbres. JSON n'impose pas que des tableaux imbriqués aient la même longueur (un tableau « déchiqueté » est valide). Pour une matrice rectangulaire, imposez-le par schéma ou code applicatif.

json
{
  "matrix": [
    [1, 2, 3],
    [4, 5, 6],
    [7, 8, 9]
  ],
  "ragged": [[1, 2], [3, 4, 5], [6]]
}

// Arrays can nest arbitrarily deep.
// JSON does not enforce rectangular shape—use a schema if needed.

Tableau d'objets

Un tableau d'objets est le pattern le plus courant pour les listes d'enregistrements (users, produits, posts). Chaque élément a typiquement la même forme, mais JSON ne l'impose pas — employez un schéma (JSON Schema 'items') pour valider que tous les éléments se conforment.

json
{
  "users": [
    { "id": 1, "name": "Alice" },
    { "id": 2, "name": "Bob" },
    { "id": 3, "name": "Carol" }
  ],
  "empty": []
}

// A very common pattern: a list of records.
// Each element is an object with the same shape.

Tableaux vides et à un élément

Les tableaux vides [] et à un élément sont valides. En conception d'API, distinguez [] (présent, liste vide) de null (présent, pas de liste) et d'une clé manquante (champ non applicable). Renvoyer [] pour « aucun élément » est généralement plus sympathique que null.

json
{
  "empty": [],
  "single": [42],
  "tags": [],
  "items": ["one"]
}

// Both forms are valid.
// Distinguish [] from null and from a missing key:
//   "tags": []      -> present, empty list
//   "tags": null    -> present, no list
//   // (no tags)    -> missing key

Accès aux tableaux dans le code

Après parsing, les tableaux JSON deviennent des tableaux/listes natifs de votre langage (Array JS, list Python, List Java, etc.). Employez l'accès par index, la longueur et l'itération standard. Bornes et sûreté de type sont de votre responsabilité — JSON n'impose pas lui-même les types d'éléments.

json
{
  "list": ["a", "b", "c"]
}

// JavaScript:
//   const arr = JSON.parse(json).list;
//   arr[0]            // "a"
//   arr.length        // 3
//   arr.includes("b") // true
//   arr.map(x => x.toUpperCase())  // ["A", "B", "C"]

// Python:
//   data = json.loads(json_str)
//   data["list"][0]   # "a"
//   len(data["list"]) # 3
07

Objets

Bases des objets

Les objets JSON sont des collections non ordonnées de paires clé/valeur enveloppées dans { }. Les clés doivent être des chaînes entre guillemets doubles ; les valeurs peuvent être de tout type JSON. Les paires se séparent par des virgules, sans virgule finale. Les objets sont la structure JSON de premier niveau la plus courante.

json
{
  "id": 1,
  "name": "Alice",
  "email": "[email protected]",
  "active": true
}

// Objects are unordered { } collections of key/value pairs.
// Keys MUST be double-quoted strings.
// Pairs are comma-separated (no trailing comma).

Règles de nommage des clés

Les clés JSON peuvent être toute chaîne entre guillemets doubles, y compris vides, avec espaces, points ou chiffres. Mais pour la clarté des API, préférez camelCase, snake_case ou kebab-case cohérents. Évitez espaces, points (conflit avec la syntaxe de chemin) et clés vides dans les API publiques.

json
{
  "simple": "ok",
  "with-dash": "ok",
  "with_underscore": "ok",
  "with.dot": "ok",
  "with space": "ok (but avoid)",
  "123numeric": "ok (but avoid)",
  "": "empty key is valid"
}

// Keys are arbitrary strings (double-quoted).
// Convention: use camelCase, snake_case, or kebab-case consistently.
// Avoid empty keys and keys with spaces/dots in APIs.

Objets imbriqués

Les objets peuvent s'imbriquer à toute profondeur, utile pour les données hiérarchiques. L'imbrication profonde est valide mais nuit à la lisibilité et augmente le couplage. Pour les API publiques, préférez une structure plus plate ou des références (IDs) au lieu d'arbres profondément imbriqués.

json
{
  "user": {
    "name": "Alice",
    "address": {
      "street": "123 Main St",
      "city": "NYC",
      "geo": { "lat": 40.7, "lng": -74.0 }
    }
  }
}

// Objects can nest arbitrarily deep.
// Deep nesting is valid but can hurt readability—flatten when sensible.

Objets avec tableaux

Combiner objets (pour les champs clés) et tableaux (pour les listes ordonnées) modélise presque toute donnée réelle. Un pattern courant est un objet enveloppant des tableaux d'objets imbriqués (un user avec ses orders). Employez un schéma pour documenter et valider la forme attendue.

json
{
  "user": {
    "name": "Alice",
    "roles": ["admin", "user"],
    "orders": [
      { "id": 1, "total": 19.99 },
      { "id": 2, "total": 5.99 }
    ]
  }
}

// Combining objects and arrays models most real-world data.

Ordre des membres

La spécification JSON traite les objets comme non ordonnés. En pratique, la plupart des parseurs modernes (V8 JavaScript, Python 3.7+, LinkedHashMap Java) conservent l'ordre d'insertion, mais n'en dépendez pas pour la correction. Si l'ordre compte pour le hachage ou la signature, triez explicitement les clés.

json
{
  "z": 1,
  "a": 2,
  "m": 3
}

// JSON objects are SPECIFIED as unordered.
// In practice, most parsers (JS, Python 3.7+) preserve insertion order.
// DO NOT rely on order for correctness—sort keys if order matters.

// Sorting keys (e.g., for stable hashing):
//   JSON.stringify(obj, Object.keys(obj).sort())

Clés dupliquées

La spécification JSON n'interdit pas les clés dupliquées, mais leur comportement est indéfini — la plupart des parseurs gardent la dernière valeur, certains la première. Les clés dupliquées sont une source fréquente de bugs subtils. JSON Schema peut imposer uniqueKeys ; les linters et parseurs stricts peuvent les rejeter.

json
// Technically valid JSON, but behavior is UNDEFINED:
{
  "name": "Alice",
  "name": "Bob"
}

// Most parsers keep the LAST value ("Bob"),
// but some keep the first. Avoid duplicate keys!

// JSON Schema (draft 2019-09+) has 'uniqueKeys' to forbid them.
// JSON.parse in JS keeps the last value (object property override).
08

Structures imbriquées

Imbrication profonde

JSON autorise une profondeur d'imbrication arbitraire, mais les structures très profondes nuisent à la lisibilité et peuvent heurter des limites de parseur (beaucoup imposent un plafond de profondeur, ex. 1000, pour prévenir le déni de service). Préférez des structures plus plates avec IDs/références pour les données très hiérarchiques.

json
{
  "a": {
    "b": {
      "c": {
        "d": {
          "e": { "value": 42 }
        }
      }
    }
  }
}

// Nesting depth is theoretically unlimited.
// Many parsers impose a limit (e.g., 1000) to prevent DoS.
// Deep nesting hurts readability—consider flattening or references.

Exemple réel

Le JSON réel mélange objets et tableaux pour modéliser entités et relations. Cet exemple de commande imbrique customer, items (un tableau d'objets) et shipping. Employez un schéma pour documenter la forme ; gardez une imbrication modérée pour la lisibilité.

json
{
  "order": {
    "id": "ord-123",
    "customer": {
      "id": "cus-1",
      "name": "Alice",
      "email": "[email protected]"
    },
    "items": [
      { "sku": "A1", "qty": 2, "price": 9.99 },
      { "sku": "B2", "qty": 1, "price": 19.99 }
    ],
    "shipping": {
      "address": { "city": "NYC", "zip": "10001" },
      "method": "express"
    },
    "total": 39.97
  }
}

Structures arborescentes

Les arbres se modélisent récursivement : chaque nœud a une valeur et un tableau de nœuds enfants. Ce pattern apparaît dans les systèmes de fichiers, organigrammes et AST. Attention aux cycles — JSON n'a pas de syntaxe de référence, les graphes cycliques doivent employer des IDs ou se sérialiser en liste plate avec pointeurs parent.

json
{
  "name": "root",
  "children": [
    {
      "name": "child-a",
      "children": [
        { "name": "grandchild-1", "children": [] },
        { "name": "grandchild-2", "children": [] }
      ]
    },
    { "name": "child-b", "children": [] }
  ]
}

// Recursive structures: a node contains an array of child nodes.

Accéder aux valeurs imbriquées

Accéder à des valeurs profondément imbriquées risque TypeError/KeyError si des clés intermédiaires manquent. Employez le chaînage optionnel (JS ?. et ??) ou le .get() chaîné (Python) avec défauts. Des bibliothèques comme lodash.get ou jq simplifient l'extraction profonde et fournissent des défauts.

json
{
  "user": { "address": { "city": "NYC" } }
}

// JavaScript (optional chaining):
//   const city = data?.user?.address?.city ?? "unknown";

// Python:
//   city = data.get("user", {}).get("address", {}).get("city", "unknown")

// Deep access without guards throws on missing keys.
// Use optional chaining or a helper like lodash.get.

Aplatir des données imbriquées

Aplatir les objets imbriqués (ex. 'user.name' au lieu de { user: { name } }) simplifie l'accès pour les variables d'environnement, champs de formulaires et indexation de recherche. Le compromis : perte de structure et aller-retour plus difficile. Employez une bibliothèque (flat, lodash) pour flatten/unflatten.

json
// Nested form:
{ "user": { "name": "Alice", "city": "NYC" } }

// Flattened form (dot notation):
{ "user.name": "Alice", "user.city": "NYC" }

// Flattened form (separate keys):
{ "userName": "Alice", "userCity": "NYC" }

// Use cases: environment variables, form fields, search indexing.
// Trade-off: simpler access vs. loss of structure.
09

JSON Schema

Bases du schéma

JSON Schema est un vocabulaire JSON pour décrire et valider des documents JSON. La racine déclare $schema (version du draft) et type. Properties liste les champs avec leurs types ; required liste les clés obligatoires. Des validateurs comme Ajv (JS) ou jsonschema (Python) vérifient la conformité.

json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://example.com/user.json",
  "title": "User",
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "age": { "type": "integer", "minimum": 0 }
  },
  "required": ["name"]
}

Validation de type

Le mot-clé 'type' valide le type JSON d'une valeur : string, number, integer, boolean, null, array ou object. Il peut être un type unique ou un tableau (ex. ['string', 'null'] pour une chaîne nullable optionnelle). 'integer' correspond aux nombres sans partie fractionnaire.

json
{
  "type": "object",
  "properties": {
    "name":   { "type": "string" },
    "age":    { "type": "integer" },
    "active": { "type": "boolean" },
    "score":  { "type": "number" },
    "tags":   { "type": "array", "items": { "type": "string" } },
    "meta":   { "type": "object" },
    "middle": { "type": ["string", "null"] }
  }
}

// 'type' can be a single type or an array of allowed types.

Contraintes de chaînes

Contraintes de chaînes : minLength, maxLength, pattern (regex), enum (valeurs autorisées) et format (indice sémantique comme 'email', 'uri', 'date-time', 'ipv4'). 'format' ne sert d'annotation que par défaut — les validateurs doivent l'activer pour l'imposer. Employez pattern pour une validation regex stricte.

json
{
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "format": "email",
      "maxLength": 254
    },
    "username": {
      "type": "string",
      "pattern": "^[a-zA-Z0-9_]{3,20}$",
      "minLength": 3,
      "maxLength": 20
    },
    "bio": { "type": "string", "maxLength": 500 }
  }
}

// 'format' is a semantic hint (email, uri, date, ipv4).
// 'pattern' is a regular expression.

Contraintes de nombres

Contraintes de nombres : minimum, maximum (inclusifs), exclusiveMinimum, exclusiveMaximum et multipleOf. Pour le type 'integer', les valeurs ne doivent pas avoir de partie fractionnaire. Combinez les contraintes pour modéliser des plages (ex. une note de 1 à 5).

json
{
  "type": "object",
  "properties": {
    "age":   { "type": "integer", "minimum": 0, "maximum": 150 },
    "price": { "type": "number", "minimum": 0, "exclusiveMinimum": 0 },
    "rating":{ "type": "integer", "minimum": 1, "maximum": 5 },
    "count": { "type": "integer", "multipleOf": 5 }
  }
}

// minimum/maximum are inclusive;
// exclusiveMinimum/exclusiveMaximum are exclusive.

Contraintes d'objets et tableaux

Contraintes de tableaux : items (schéma d'élément), minItems, maxItems, uniqueItems. Contraintes d'objets : required (clés obligatoires), properties (schémas de champs), additionalProperties (false pour interdire les clés en plus, ou un schéma pour elles), minProperties, maxProperties.

json
{
  "type": "object",
  "properties": {
    "id":   { "type": "integer" },
    "tags": {
      "type": "array",
      "items": { "type": "string" },
      "minItems": 1,
      "maxItems": 10,
      "uniqueItems": true
    }
  },
  "required": ["id"],
  "additionalProperties": false
}

// minItems/maxItems/uniqueItems constrain arrays.
// required lists mandatory keys; additionalProperties
// controls whether extra keys are allowed.

Validation avancée

JSON Schema avancé : oneOf/anyOf/allOf combinent des sous-schémas ; $ref référence des définitions réutilisables ; if/then/else applique une validation conditionnelle ; const exige une valeur exacte ; enum liste les valeurs autorisées. Cela permet d'exprimer des contraintes riches et des types réutilisables.

json
{
  "oneOf": [
    { "type": "string" },
    { "type": "integer" }
  ],
  "definitions": {
    "address": {
      "type": "object",
      "properties": { "city": { "type": "string" } }
    }
  },
  "properties": {
    "home": { "$ref": "#/definitions/address" },
    "work": { "$ref": "#/definitions/address" }
  },
  "if":   { "properties": { "type": { "const": "vip" } } },
  "then": { "required": ["discount"] }
}

// oneOf/anyOf/allOf combine schemas.
// $ref reuses definitions; if/then/else is conditional.
10

JSONPath

Syntaxe JSONPath

JSONPath est un langage de requête pour JSON, inspiré de XPath. '$' est la racine, '.' sélectionne un enfant, '[index]' un élément de tableau, '*' un joker, et '..' la descente récursive. Des bibliothèques comme jsonpath-plus (JS) ou jsonpath-ng (Python) l'implémentent.

json
// JSONPath queries JSON like XPath queries XML.

// Sample data:
{
  "store": {
    "book": [
      { "category": "fiction", "price": 12.99 },
      { "category": "web",     "price": 29.99 }
    ]
  }
}

// Common JSONPath expressions:
$.store.book[0].category      // "fiction"
$.store.book[*].price         // [12.99, 29.99]
$..price                      // all prices anywhere
$.store..category             // all categories under store

Racine et enfant

'$' référence la racine. '.' sélectionne un enfant par nom ; '[]' est l'alternative à crochets qui gère les clés avec points, espaces ou guillemets. '[index]' sélectionne un élément de tableau (base 0) ; certaines implémentations acceptent les indices négatifs pour compter depuis la fin.

json
// '$' = root object/array
// '.' or '[]' = child

$.user.name              // dot notation
$['user']['name']        // bracket notation (use for special chars)
$.users[0]               // first element of users array
$.users[-1]              // last element (some implementations)

// Use bracket notation when keys contain dots, spaces, or quotes:
$['user.name']
$['first name']

Descente récursive

'..' (descente récursive) matche une clé ou un élément à toute profondeur. '$..price' renvoie chaque valeur 'price' peu importe où elle apparaît. '$..*' renvoie chaque nœud. Inestimable pour chercher dans un JSON grand ou profondément imbriqué quand on ignore le chemin exact.

json
{
  "a": { "b": { "c": 1 }, "c": 2 }
}

// '..' searches at all depths:
$..c                      // [1, 2] (all 'c' keys anywhere)
$..a                      // all 'a' keys
$..*                      // every node (everything)

// Useful for finding a key without knowing the exact path:
$..price                  // every price, no matter how nested

Expressions de filtre

Les filtres emploient [?(expression)] où '@' désigne l'élément courant. Les opérateurs gérés varient selon l'implémentation mais incluent typiquement ==, !=, <, <=, >, >=, && (et), || (ou), et parfois =~ pour les regex. Des fonctions comme length() et contains() ajoutent de la puissance.

json
// Filter with [?(expression)]:

$.store.book[?(@.price < 20)]            // books under 20
$.store.book[?(@.category == 'web')]     // web books
$.store.book[?(@.price < 30 && @.category == 'web')]

// '@' refers to the current item being filtered.
// Operators: == != < <= > >= && || =~ (regex in some impls)
// Functions: length(), contains(), matches()

Jokers

'*' est un joker qui matche tous les enfants d'un objet ou tous les éléments d'un tableau. '$.users[*].name' renvoie le 'name' de chaque utilisateur. '$..*' renvoie chaque nœud. Les résultats reviennent en tableau de correspondances, même s'il n'y en a qu'une.

json
{
  "users": [
    { "name": "Alice", "age": 30 },
    { "name": "Bob",   "age": 25 }
  ]
}

// '*' matches all elements/children:
$.users[*]               // all user objects
$.users[*].name          // ["Alice", "Bob"]
$.users[0].*             // all values of first user: ["Alice", 30]
$..*                     // every node in the document

// Wildcards return arrays of matches.

Fonctions courantes et exemples

Les fonctions JSONPath varient selon l'implémentation : length(), min(), max(), avg(), sum(), contains() et matches() sont courantes. Combinez filtres et descente récursive pour des requêtes puissantes. En ligne de commande, jq est le standard de facto et emploie une syntaxe légèrement différente.

json
// length(): array length or string length
$.users.length()                    // number of users
$.store.book[?(@.title.length() > 10)]

// min(), max(), avg(), sum() (some implementations)
$.store.book..price.min()

// Realistic query: titles of cheap web books
$.store.book[?(@.price < 20 && @.category == 'web')].title

// Tools: jq (CLI), jsonpath-plus (JS), jsonpath-ng (Python),
//        Jayway (Java), GoJSONQ (Go)
11

JSON vs XML et YAML

Syntaxe JSON vs XML

JSON est plus léger (pas de balises fermantes, types natifs pour nombres/booléens/null) et se mappe directement aux structures de données de la plupart des langages. XML est plus lourd mais plus riche : attributs, namespaces, contenu mixte, schémas (XSD) et transformations (XSLT). JSON domine les API web ; XML persiste en entreprise/SOAP.

json
// JSON:
{
  "name": "Alice",
  "age": 30,
  "hobbies": ["reading", "coding"]
}

<!-- XML: -->
<person>
  <name>Alice</name>
  <age>30</age>
  <hobbies>
    <hobby>reading</hobby>
    <hobby>coding</hobby>
  </hobbies>
</person>

// JSON: lighter, no closing tags, types (number/boolean/null).
// XML:  heavier, supports attributes, namespaces, mixed content.

Syntaxe JSON vs YAML

YAML emploie l'indentation au lieu des accolades/guillemets, gère les commentaires, les chaînes multi-lignes et les anchors/alias. JSON est plus strict (guillemets requis, pas de commentaires) mais plus rapide et plus universel. YAML est un sur-ensemble de JSON — tout fichier JSON valide est aussi un YAML valide.

json
# YAML:
name: Alice
age: 30
hobbies:
  - reading
  - coding

// JSON (equivalent):
{
  "name": "Alice",
  "age": 30,
  "hobbies": ["reading", "coding"]
}

// YAML: no quotes/braces, indentation-based, supports comments.
// JSON: stricter, faster to parse, ubiquitous in APIs.

Conversion JSON vers YAML

Convertir JSON en YAML est direct puisque YAML est un sur-ensemble de JSON. Le yaml.dump de Python et js-yaml de Node s'en chargent. Le résultat emploie l'indentation et pas de guillemets (la plupart du temps). Les commentaires et chaînes multi-lignes de YAML ne proviennent pas du JSON (JSON n'en a pas).

json
// JSON input:
{ "name": "Alice", "roles": ["admin", "user"] }

// YAML output:
name: Alice
roles:
  - admin
  - user

// Python:
//   import yaml, json
//   yaml.dump(json.loads(json_str), sort_keys=False)

// Node.js:
//   const yaml = require('js-yaml');
//   yaml.dump(JSON.parse(jsonStr));

Conversion YAML vers JSON

Convertir YAML en JSON fonctionne pour un YAML simple mais perd les spécificités YAML : commentaires, anchors/alias, flux multi-documents, tags et clés complexes. Employez yaml.safe_load pour éviter l'exécution de code arbitraire depuis des tags personnalisés. Le résultat est du JSON standard.

json
# YAML input:
server:
  host: localhost
  port: 8080
  debug: true

// JSON output:
{
  "server": {
    "host": "localhost",
    "port": 8080,
    "debug": true
  }
}

// Python:
//   import yaml, json
//   json.dumps(yaml.safe_load(yaml_str), indent=2)

// Watch for YAML-specific features: anchors, tags, multi-docs.

Différences de modélisation

JSON modélise les données en objets et tableaux — pas d'attributs ni namespaces. XML ajoute attributs, namespaces, contenu mixte et schémas riches. YAML ajoute commentaires, anchors et multi-documents. TOML vise les fichiers de config avec tables. Choisissez selon le besoin : API (JSON), documents (XML), config (YAML/TOML).

json
// JSON: objects and arrays, no attributes.
//   Attribute-style metadata needs a convention (e.g., @_prefix).

// XML: elements + attributes, namespaces, mixed content.
//   <book id="b1" category="web"><title>...</title></book>

// YAML: maps, sequences, scalars, anchors, multi-doc.
//   Supports comments and multi-line strings natively.

// TOML: tables + key/value, designed for config files.
//   Best for configuration; not ideal for nested data.

Quand employer chaque format

JSON pour les API web et le stockage NoSQL (universel, rapide). XML pour les services d'entreprise, les données centrées document (SVG, XHTML) et les schémas riches. YAML pour la config rédigée par des humains (CI/CD, docker-compose) grâce aux commentaires et à la lisibilité. TOML pour les petits fichiers de config. Accordez le format au cas d'usage.

json
// Use JSON when:
//   - building web/REST APIs (universal browser support)
//   - storing structured data (NoSQL databases)
//   - configuration with simple needs (package.json)

// Use XML when:
//   - enterprise/SOAP web services
//   - documents with mixed content (SVG, XHTML, DocBook)
//   - you need schemas, namespaces, or XSLT transforms

// Use YAML when:
//   - human-written config (CI/CD, docker-compose)
//   - you need comments and multi-line strings

// Use TOML when:
//   - small config files (Cargo, pyproject)
12

Parsing en JavaScript

JSON.parse

JSON.parse convertit une chaîne JSON en valeur JavaScript. Il accepte toute valeur JSON valide (objet, tableau, chaîne, nombre, booléen, null). Un JSON invalide lève une SyntaxError. Enveloppez toujours JSON.parse dans un try/catch avec des entrées non fiables.

json
// Parse a JSON string into a JavaScript value.
const json = '{"name":"Alice","age":30}';
const obj = JSON.parse(json);

console.log(obj.name); // "Alice"
console.log(obj.age);  // 30

// JSON.parse accepts a string only.
// Passing a number/boolean/object throws or coerces.
// JSON.parse("42")    === 42       (valid)
// JSON.parse("true")  === true     (valid)
// JSON.parse("null")  === null     (valid)
// JSON.parse(undefined) // throws SyntaxError

JSON.stringify

JSON.stringify convertit une valeur JavaScript en chaîne JSON. Fonctions, Symbols et undefined sont omis (dans les objets) ou transformés en null (dans les tableaux). BigInt lève TypeError — convertissez-le d'abord en chaîne. Employez le troisième argument (espace) pour le pretty-printing.

json
// Serialize a JavaScript value to a JSON string.
const obj = { name: "Alice", age: 30 };
const json = JSON.stringify(obj);
// '{"name":"Alice","age":30}'

// Pretty-print with 2-space indent:
JSON.stringify(obj, null, 2);
// {
//   "name": "Alice",
//   "age": 30
// }

// Functions, Symbols, and undefined are omitted.
// BigInt throws; use a replacer or String() first.

Fonction reviver

Le reviver de JSON.parse transforme les valeurs pendant le parsing. Il est appelé de bas en haut pour chaque paire clé/valeur (racine comprise, avec clé ''). Renvoyez la valeur transformée, ou undefined pour omettre la propriété. Utile pour le parsing de dates, BigInt et types personnalisés.

json
// JSON.parse accepts a 'reviver' to transform values.
const json = '{"date":"2024-01-15","count":"42"}';

const obj = JSON.parse(json, (key, value) => {
  if (key === "date") return new Date(value);
  if (key === "count") return Number(value);
  return value;
});

// obj.date is a Date object; obj.count is a number.

// Reviver is called bottom-up for every key, including the root.

Fonction replacer

Le replacer de JSON.stringify filtre ou transforme les valeurs pendant la sérialisation. En fonction, il est appelé pour chaque clé — renvoyez undefined pour omettre une propriété. En tableau, il agit comme une liste blanche de clés à inclure. Utile pour masquer des secrets et sélectionner des champs.

json
// JSON.stringify accepts a 'replacer' to filter/transform.
const obj = { name: "Alice", password: "secret", age: 30 };

// Replacer as a function:
const safe = JSON.stringify(obj, (key, value) => {
  if (key === "password") return undefined; // omit
  return value;
});
// '{"name":"Alice","age":30}'

// Replacer as an array (allowlist of keys):
JSON.stringify(obj, ["name", "age"]);
// '{"name":"Alice","age":30}'

Pretty printing

Passez un argument espace à JSON.stringify pour le pretty-printing : un nombre (profondeur d'indentation) ou une chaîne (ex. '\t'). Pour un ordre de clés stable (utile pour hachage ou signature), triez les clés avant de sérialiser. Combinez avec un replacer pour filtrer les champs tout en indentant.

json
const obj = { name: "Alice", age: 30 };

// Compact (default):
JSON.stringify(obj);
// '{"name":"Alice","age":30}'

// 2-space indent:
JSON.stringify(obj, null, 2);

// Tab indent:
JSON.stringify(obj, null, "\t");

// Combine replacer and indent:
JSON.stringify(obj, ["name", "age"], 2);

// To insert a stable key order, sort keys first:
const sorted = Object.keys(obj).sort()
  .reduce((acc, k) => (acc[k] = obj[k], acc), {});
JSON.stringify(sorted, null, 2);

Gestion des erreurs

JSON.parse lève SyntaxError sur une entrée invalide — enveloppez-le toujours dans un try/catch avec des données non fiables. Causes courantes : virgules finales, guillemets simples, commentaires ou entrée tronquée. Pour du JSON très grand ou profondément imbriqué, envisagez un parseur en flux ou une limite de profondeur pour prévenir le déni de service.

json
// Always wrap JSON.parse in try/catch for untrusted input.
function safeParse(str) {
  try {
    return { ok: true, value: JSON.parse(str) };
  } catch (e) {
    return { ok: false, error: e.message };
  }
}

// Common errors:
//   SyntaxError: Unexpected token
//   SyntaxError: Unexpected end of JSON input
//   (no undefined/NaN/Infinity accepted)

// For deeply nested untrusted JSON, limit depth to avoid DoS.
// Consider a streaming parser for very large files.
13

Parsing en Python

json.loads

json.loads parse une chaîne JSON en objets Python. Les objets JSON deviennent des dicts, les tableaux des listes, les chaînes des str, les nombres des int ou float automatiquement, true/false deviennent True/False, et null devient None. 'loads' signifie 'load string'.

json
import json

json_str = '{"name": "Alice", "age": 30}'
data = json.loads(json_str)

print(data["name"])  # Alice
print(data["age"])   # 30

# loads = "load string"
# Returns Python objects: dict, list, str, int/float, bool, None
# JSON true/false/null  ->  Python True/False/None
# JSON numbers          ->  int or float (auto)

json.dumps

json.dumps sérialise un objet Python en chaîne JSON. Employez indent pour le pretty-printing, ensure_ascii=False pour garder les caractères Unicode (au lieu d'échappements \uXXXX), et sort_keys=True pour une sortie stable. True/False/None Python se mappent à true/false/null JSON.

json
import json

data = {"name": "Alice", "age": 30, "active": True}

# Compact:
json.dumps(data)
# '{"name": "Alice", "age": 30, "active": true}'

# Pretty-printed:
json.dumps(data, indent=2, ensure_ascii=False)
# {
#   "name": "Alice",
#   "age": 30,
#   "active": true
# }

# ensure_ascii=False keeps Unicode characters readable.
# sort_keys=True produces stable output.

Parser des fichiers

Employez json.load (objet fichier) et json.dump (objet fichier) pour les fichiers ; json.loads et json.dumps pour les chaînes. Ouvrez toujours les fichiers avec encoding='utf-8' pour éviter les défauts de plateforme. Pour les gros fichiers, considérez ijson (flux) ou orjson (plus rapide) pour de meilleures performances.

json
import json

# Read from a file:
with open("data.json", "r", encoding="utf-8") as f:
    data = json.load(f)

# Write to a file:
with open("out.json", "w", encoding="utf-8") as f:
    json.dump(data, f, indent=2, ensure_ascii=False)

# load/dump work on file objects; loads/dumps work on strings.
# Always specify encoding="utf-8" for portability.

Encodeurs personnalisés

Héritez de json.JSONEncoder et surchargez default() pour sérialiser les types que JSON ne gère pas nativement (datetime, set, Decimal, classes personnalisées). Renvoyez une représentation sérialisable en JSON. Pour le décodage, écrivez un hook personnalisé (object_hook) pour inverser la transformation.

json
import json
from datetime import datetime, date

class CustomEncoder(json.JSONEncoder):
    def default(self, obj):
        if isinstance(obj, (datetime, date)):
            return obj.isoformat()
        if isinstance(obj, set):
            return sorted(obj)
        return super().default(obj)

data = {"now": datetime.now(), "tags": {"a", "b"}}
json.dumps(data, cls=CustomEncoder)
# '{"now": "2024-...", "tags": ["a", "b"]}'

# The default() method is called for objects json can't serialize.

Gestion des erreurs

json.loads lève json.JSONDecodeError sur une entrée invalide, avec les infos ligne/colonne. Causes courantes : virgules finales, guillemets simples, commentaires, NaN/Infinity (rejetés par défaut) et caractères de contrôle dans les chaînes. Employez parse_constant pour gérer NaN/Infinity/-Infinity au besoin.

json
import json

def safe_loads(s):
    try:
        return {"ok": True, "value": json.loads(s)}
    except json.JSONDecodeError as e:
        return {"ok": False, "error": str(e), "line": e.lineno, "col": e.colno}

# json.JSONDecodeError gives line and column of the error.
# Common causes: trailing commas, single quotes, comments,
#   NaN/Infinity (rejected by default), control chars in strings.

# To allow NaN/Infinity (non-standard):
json.loads('{"x": NaN}', parse_constant=lambda x: None)  # or float(x)

Travailler avec Decimal et DateTime

Par défaut, json parse tous les nombres en float, perdant la précision des décimaux comme l'argent. Passez parse_float=Decimal pour conserver la précision, et sérialisez avec un hook default qui reconvertit Decimal (en str pour préserver la précision, ou float si la perte est acceptable). Employez str pour une représentation exacte de l'argent.

json
import json
from decimal import Decimal
from datetime import datetime

# Decimal: parse_float keeps precision (default would lose it)
data = json.loads('{"price": 19.99}', parse_float=Decimal)
print(data["price"])        # Decimal('19.99')
print(data["price"] + Decimal("0.01"))  # 20.00 exact

# Serialize Decimal back:
def encode(obj):
    if isinstance(obj, Decimal):
        return float(obj)   # or str(obj) to keep precision
    raise TypeError

json.dumps({"price": Decimal("19.99")}, default=encode)

# parse_float=float is the default; use Decimal for money.
14

Parsing en Java

Bases de Jackson

Jackson est la bibliothèque JSON Java la plus populaire. ObjectMapper.readValue parse le JSON en POJOs ; writeValueAsString les sérialise. Ajoutez jackson-databind (plus jackson-core et jackson-annotations) comme dépendances. Jackson est rapide, mature et s'intègre à Spring Boot par défaut.

json
import com.fasterxml.jackson.databind.ObjectMapper;

ObjectMapper mapper = new ObjectMapper();

// Parse JSON to a Java object:
String json = "{\"name\":\"Alice\",\"age\":30}";
User user = mapper.readValue(json, User.class);

// Serialize a Java object:
String out = mapper.writeValueAsString(user);

// Pretty-print:
String pretty = mapper.writerWithDefaultPrettyPrinter()
                      .writeValueAsString(user);

// Jackson is the de facto JSON library for Java.
// Add: com.fasterxml.jackson.core:jackson-databind

Bases de Gson

Gson est la bibliothèque JSON de Google, plus simple que Jackson pour un usage basique. Gson.fromJson parse ; toJson sérialise. Employez GsonBuilder pour les options (pretty printing, sérialisation des null, adaptateurs personnalisés). Ajoutez com.google.code.gson:gson comme dépendance. Gson est courant sur Android.

json
import com.google.gson.Gson;

Gson gson = new Gson();

// Parse:
User user = gson.fromJson(json, User.class);

// Serialize:
String out = gson.toJson(user);

// Pretty-print:
Gson pretty = new GsonBuilder().setPrettyPrinting().create();
String s = pretty.toJson(user);

// Gson (by Google) is simpler than Jackson for basic use.
// Add: com.google.code.gson:gson

Modèle arborescent JsonNode

Le JsonNode de Jackson est un modèle arborescent pour naviguer le JSON sans POJO. Employez get() (renvoie null si absent) ou path() (renvoie un « nœud manquant » sûr pour le chaînage). asText/asInt/asBoolean ont des surcharges avec valeur par défaut. Utile quand le schéma est inconnu ou variable.

json
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;

ObjectMapper mapper = new ObjectMapper();
JsonNode root = mapper.readTree(json);

String name = root.get("name").asText();     // "Alice"
int age = root.get("age").asInt();            // 30
JsonNode hobbies = root.get("hobbies");       // array
for (JsonNode h : hobbies) {
    System.out.println(h.asText());
}

// get() returns null for missing keys; path() returns a
// 'missing node' that you can chain safely.
String city = root.path("address").path("city").asText("unknown");

Désérialisation personnalisée

Un JsonDeserializer personnalisé traite les encodages JSON non standards (ex. '$19.99' pour l'argent). Annotez un champ avec @JsonDeserialize(using = ...) ou enregistrez un SimpleModule pour un type. Employez JsonSerializer pour une sérialisation personnalisée. Cela garde vos POJOs exempts de logique de parsing.

json
import com.fasterxml.jackson.databind.*;
import com.fasterxml.jackson.core.*;
import java.io.IOException;

public class MoneyDeserializer extends JsonDeserializer<Double> {
    @Override
    public Double deserialize(JsonParser p, DeserializationContext ctxt)
            throws IOException {
        String s = p.getText();           // e.g. "$19.99"
        return Double.parseDouble(s.replaceAll("[^0-9.]", ""));
    }
}

// Annotate the field:
//   @JsonDeserialize(using = MoneyDeserializer.class)
//   public double price;

// Or register a module for a type.

API en flux

L'API en flux de Jackson (JsonParser/JsonGenerator) lit et écrit le JSON jeton par jeton avec une mémoire constante — idéal pour d'énormes fichiers. Vous contrôlez la boucle de parsing et pouvez sauter des sous-arbres avec skipChildren(). Associez-le au modèle arborescent ou POJO pour les parties réellement nécessaires.

json
import com.fasterxml.jackson.core.*;

// Jackson streaming: low memory, fast, for huge files.
JsonFactory f = new JsonFactory();
try (JsonParser p = f.createParser(new File("huge.json"))) {
    while (p.nextToken() != JsonToken.END_OBJECT) {
        String field = p.getCurrentName();
        if ("name".equals(field)) {
            p.nextToken();
            System.out.println(p.getText());
        }
        // skip complex values you don't need:
        // p.skipChildren();
    }
}

// Use streaming for files that won't fit in memory.
15

Parsing en PHP

json_encode

json_encode sérialise une valeur PHP en JSON. Les tableaux PHP deviennent des objets JSON (associatifs) ou des tableaux (séquentiels). Flags courants : JSON_PRETTY_PRINT, JSON_UNESCAPED_UNICODE (garde un Unicode lisible), JSON_UNESCAPED_SLASHES (n'échappe pas /). Combinez les flags avec l'opérateur |.

json
<?php
$data = ["name" => "Alice", "age" => 30, "active" => true];

// Compact (default):
$json = json_encode($data);
// {"name":"Alice","age":30,"active":true}

// Pretty-print:
$pretty = json_encode($data, JSON_PRETTY_PRINT);

// Keep Unicode readable (don't escape to \uXXXX):
$unicode = json_encode($data, JSON_UNESCAPED_UNICODE);

// Combine flags with |:
json_encode($data, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE
           | JSON_UNESCAPED_SLASHES);

json_decode

json_decode parse le JSON en PHP. Le second argument contrôle le résultat : true renvoie des tableaux associatifs, false (défaut) des objets stdClass. Choisissez selon votre style d'accès ($arr['key'] vs $obj->key). Les tableaux PHP à clés non séquentielles deviennent des objets JSON.

json
<?php
$json = '{"name":"Alice","age":30,"hobbies":["reading"]}';

// Default: returns associative array OR object (stdClass)
$data = json_decode($json);
echo $data->name;            // Alice

// Force associative array:
$arr = json_decode($json, true);
echo $arr["name"];           // Alice

// The second argument (assoc) controls array vs object.
// PHP objects become stdClass instances by default.

Gestion des erreurs

Le json_decode de PHP ne lève pas par défaut — vérifiez json_last_error() et json_last_error_msg() après parsing. Passez JSON_THROW_ON_ERROR (PHP 7.3+) pour qu'il lève une JsonException à la place, ce qui est plus propre. Erreurs courantes : virgules finales, guillemets simples et UTF-8 invalide.

json
<?php
$json = '{invalid json}';
$data = json_decode($json);

if (json_last_error() !== JSON_ERROR_NONE) {
    echo "Parse error: " . json_last_error_msg();
    // e.g., "Syntax error"
}

// PHP does not throw on JSON errors; check json_last_error().
// Common errors: trailing comma, single quotes, invalid UTF-8.

// To throw exceptions instead:
try {
    $data = json_decode($json, true, 512, JSON_THROW_ON_ERROR);
} catch (JsonException $e) {
    echo $e->getMessage();
}

Pretty print et flags

Flags json_encode courants : JSON_PRETTY_PRINT (indentation), JSON_UNESCAPED_UNICODE (garde un non-ASCII lisible), JSON_UNESCAPED_SLASHES (n'échappe pas /), JSON_NUMERIC_CHECK (convertit les chaînes numériques en nombres), JSON_THROW_ON_ERROR (lève en cas d'échec). Combinez avec |.

json
<?php
$data = ["path" => "C:\\Users", "url" => "https://x.com/"];

// Default escapes / and non-ASCII:
json_encode($data);
// {"path":"C:\\Users","url":"https:\/\/x.com\/"}

// Cleaner output:
json_encode($data, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE
           | JSON_PRETTY_PRINT);
// {
//     "path": "C:\\Users",
//     "url": "https://x.com/"
// }

// JSON_NUMERIC_CHECK converts numeric strings to numbers:
json_encode(["id" => "42"], JSON_NUMERIC_CHECK);  // {"id":42}

Sérialisation personnalisée

Implémentez JsonSerializable et définissez jsonSerialize() pour contrôler comment un objet s'encode. C'est la façon la plus propre de masquer des champs (ex. omettre le mot de passe), renommer des clés ou calculer des valeurs dérivées pendant la sérialisation. La méthode renvoie toute structure sérialisable en JSON.

json
<?php
class User implements JsonSerializable {
    public $name;
    public $password;

    public function __construct($name, $password) {
        $this->name = $name;
        $this->password = $password;
    }

    public function jsonSerialize(): mixed {
        return [
            "name" => $this->name,
            // omit password for security
        ];
    }
}

echo json_encode(new User("Alice", "secret"));
// {"name":"Alice"}

// JsonSerializable lets the class control its JSON form.
16

Spécification JSON:API

Structure du document

JSON:API est une spécification pour construire des API JSON cohérentes. Un document a un objet 'jsonapi' de version au premier niveau, une ressource primaire 'data', des ressources liées 'included' optionnelles, 'meta' pour les infos non standards, 'links' pour la pagination et 'errors' pour les échecs. Le type média est application/vnd.api+json.

json
{
  "jsonapi": { "version": "1.1" },
  "data": {
    "type": "articles",
    "id": "1",
    "attributes": {
      "title": "JSON:API Basics"
    },
    "relationships": {
      "author": { "data": { "type": "people", "id": "9" } }
    }
  },
  "included": [
    { "type": "people", "id": "9", "attributes": { "name": "Jane" } }
  ]
}

// JSON:API is a convention for building JSON APIs.
// Top-level keys: jsonapi, data, errors, meta, links, included.

Objets ressource

Un objet ressource JSON:API a un 'type' (le genre de ressource) et un 'id' (un identifiant en chaîne), plus 'attributes' (les données) et des 'relationships' optionnelles (liens vers d'autres ressources) et 'links' (URLs comme self). Les IDs doivent être des chaînes. Le type et l'id ne doivent pas apparaître dans attributes.

json
{
  "data": {
    "type": "articles",
    "id": "1",
    "attributes": {
      "title": "Hello",
      "published": true,
      "views": 42
    },
    "links": {
      "self": "/articles/1"
    }
  }
}

// Every resource has a 'type' (string) and 'id' (string).
// 'attributes' holds data; 'relationships' holds links to others.
// 'id' and 'type' MUST NOT appear inside attributes.

Relations

Les relations lient une ressource à d'autres via des objets identifiants de ressource ({type, id}). Les relations to-one emploient un identifiant unique ; les to-many un tableau. L'objet 'links' fournit 'self' (l'URL de la relation) et 'related' (l'URL de la ressource liée) pour la navigation.

json
{
  "data": {
    "type": "articles",
    "id": "1",
    "relationships": {
      "author": {
        "data": { "type": "people", "id": "9" },
        "links": {
          "self": "/articles/1/relationships/author",
          "related": "/articles/1/author"
        }
      },
      "tags": {
        "data": [
          { "type": "tags", "id": "1" },
          { "type": "tags", "id": "2" }
        ]
      }
    }
  }
}

// to-one: data is a single resource identifier.
// to-many: data is an array of resource identifiers.

Meta et links

'meta' transporte les informations non standards comme les totaux, limites de débit ou avertissements. 'links' fournit la navigation hypermédia : self, first, prev, next, last pour la pagination, plus les URLs related. Employez null pour un lien absent (ex. prev sur la première page).

json
{
  "meta": {
    "totalPages": 5,
    "currentPage": 1,
    "rateLimit": 100
  },
  "links": {
    "self": "/articles?page=1",
    "first": "/articles?page=1",
    "prev": null,
    "next": "/articles?page=2",
    "last": "/articles?page=5"
  },
  "data": [ /* ... */ ]
}

// meta: non-standard metadata (counts, rate limits, etc.).
// links: pagination and resource URLs.

Erreurs

Les documents d'erreur JSON:API ont un tableau 'errors' au premier niveau (et pas de 'data'). Chaque objet erreur a des champs optionnels : id, status (code HTTP en chaîne), code (propre à l'app), title (résumé court), detail (explication humaine), source (pointeur vers le champ fautif via JSON Pointer) et meta.

json
{
  "errors": [
    {
      "id": "err-123",
      "status": "404",
      "code": "NOT_FOUND",
      "title": "Resource Not Found",
      "detail": "Article 99 does not exist.",
      "source": { "pointer": "/data/attributes/id" },
      "meta": { "requestId": "abc-9" }
    }
  ]
}

// Errors is an array of error objects.
// status: HTTP status string; code: app-specific code.
// source.pointer: JSON Pointer to the offending field.
17

JSON5

Fonctionnalités de JSON5

JSON5 est un sur-ensemble de JSON conçu pour la config rédigée par des humains. Il ajoute commentaires, chaînes sans guillemets/à guillemets simples, virgules finales, nombres hexa/Infinity/NaN et formats de nombres assouplis. JSON5 n'est pas du JSON standard — employez un parseur JSON5 (package npm json5) et convertissez en JSON pour l'échange.

json
// JSON5 is a superset of JSON with friendlier syntax.
{
  // line comments
  /* block comments */
  unquotedKey: "ok",            // unquoted keys
  "with space": "ok",            // quoted keys still allowed
  singleQuote: 'single',        // single-quoted strings
  trailing: [1, 2, 3,],         // trailing commas
  hex: 0x1F,                     // hexadecimal numbers
  inf: Infinity,                 // Infinity, -Infinity, NaN
  leadingDot: .5,                // leading decimal point
  trailingDot: 5.,               // trailing decimal point
  plus: +5,                      // leading plus
}

// JSON5 is NOT standard JSON—use a JSON5 parser.

Commentaires

JSON5 gère les commentaires de ligne // et de bloc /* */, que le JSON standard interdit. Cela rend JSON5 idéal pour les fichiers de config rédigés à la main. Le settings.json de VS Code et le tsconfig.json de TypeScript emploient JSONC (JSON avec commentaires), un sous-ensemble similaire mais légèrement différent.

json
{
  // Single-line comment (like JS)
  "name": "Alice",

  /* Block comment
     spanning multiple lines */
  "age": 30,

  "active": true // end-of-line comment
}

// Standard JSON rejects comments.
// JSON5 supports // and /* */ comments everywhere.
// VS Code's settings.json and tsconfig.json use JSONC (a subset).

Virgules finales

JSON5 autorise les virgules finales après le dernier élément des objets et tableaux. Le JSON standard les rejette. Les virgules finales réduisent le bruit de diff en ajoutant ou réordonnant des champs (chaque ligne peut finir par une virgule). Beaucoup de langages et formats de config modernes l'admettent désormais.

json
{
  "a": 1,
  "b": 2,
  "c": 3,           // <-- trailing comma OK in JSON5
}

// Arrays too:
[1, 2, 3,]

// Standard JSON rejects trailing commas.
// JSON5 allows them, reducing diff noise when adding fields.

Chaînes sans guillemets et à guillemets simples

JSON5 autorise les clés identifiants sans guillemets (correspondant à [A-Za-z_$][A-Za-z0-9_$]*) et les chaînes à guillemets simples comme doubles. Dans une chaîne à guillemets simples, échappez ' en \'; dans une chaîne à guillemets doubles, échappez " en \". Cela reflète la syntaxe littérale d'objet JavaScript pour la lisibilité.

json
{
  unquoted: "value",          // unquoted identifier key
  "quoted key": "value",       // quoted key (for special chars)
  single: 'single-quoted',     // single-quoted string value
  mixed: 'it\'s ok',           // escape single quote inside
  double: "she said \"hi\"",  // escape double quote inside
}

// Unquoted keys must be valid identifiers ([A-Za-z_$][A-Za-z0-9_$]*).
// Single and double quotes are both allowed for strings.

Nombres et chaînes (étendus)

JSON5 étend les nombres : hexadécimal (0xFF), points décimaux initiaux/finaux (.5, 5.), plus initial (+5) et les mots-clés Infinity, -Infinity et NaN. Tous sont rejetés par le JSON standard. Les chaînes JSON5 emploient toujours des séquences d'échappement (\n) pour les sauts de ligne — pas de chaînes multi-lignes nues.

json
{
  hex: 0xFF,                    // hexadecimal
  leadingDot: .5,               // .5 instead of 0.5
  trailingDot: 5.,              // 5. instead of 5.0
  leadingPlus: +5,              // +5 (standard JSON rejects +)
  infinity: Infinity,           // Infinity (not in standard JSON)
  negativeInfinity: -Infinity,
  nan: NaN,
  multiline: 'line1\nline2'    // escape sequences like JSON
}

// JSON5 does NOT support real multi-line strings or bareword NaN.
18

JSON Lines (JSONL)

Format JSONL

JSON Lines (JSONL ou NDJSON) est un format où chaque ligne est une valeur JSON séparée et complète. Pas de tableau englobant. Idéal pour les flux, logs et grands jeux de données : on peut traiter ligne par ligne sans charger tout le fichier. Extensions : .jsonl, .ndjson.

json
// A JSON Lines file (.jsonl / .ndjson) is one JSON value per line:

{"name": "Alice", "age": 30}
{"name": "Bob", "age": 25}
{"name": "Carol", "age": 35}

// Rules:
//   - Each line is a COMPLETE, valid JSON value.
//   - Lines are separated by newlines (\n).
//   - No enclosing [ ] array.
//   - Each line is parsed independently.

Lire du JSONL

Lisez du JSONL en itérant les lignes et en parsant chacune avec JSON.parse/loads. Cela diffuse le fichier avec une mémoire constante — idéal pour les énormes jeux de données. Sautez les lignes vides. En Node.js, employez readline sur un flux de fichier ; en Python, itérez directement l'objet fichier. Pas besoin de charger tout le fichier.

json
// JavaScript (Node.js) — line by line:
const fs = require("fs");
const readline = require("readline");

const rl = readline.createInterface({
  input: fs.createReadStream("data.jsonl"),
  crlfDelay: Infinity,
});

for await (const line of rl) {
  if (!line.trim()) continue;
  const obj = JSON.parse(line);
  console.log(obj.name);
}

// Python:
//   import json
//   with open("data.jsonl") as f:
//       for line in f:
//           obj = json.loads(line)

Écrire du JSONL

Écrivez du JSONL en sérialisant chaque enregistrement avec JSON.stringify/dumps (compact, sans indentation) et en ajoutant un saut de ligne. Employez un flux en écriture (Node) ou ouvrez le fichier en mode écriture (Python) pour l'efficacité. La forme compacte garde les lignes courtes et parsables ; un enregistrement par ligne est la règle.

json
// JavaScript (Node.js):
const fs = require("fs");
const out = fs.createWriteStream("out.jsonl");
for (const obj of records) {
  out.write(JSON.stringify(obj) + "\n");
}
out.end();

// Python:
//   import json
//   with open("out.jsonl", "w") as f:
//       for obj in records:
//           f.write(json.dumps(obj) + "\n")

// One JSON per line; compact form (no indent) is conventional.

Cas d'usage

JSONL brille pour les fichiers de log, grands jeux de données, données d'entraînement ML, dumps de bases et flux d'événements en append. Chaque ligne est indépendante : on peut ajouter sans réécrire, reprendre le parsing après une ligne corrompue et traiter en parallèle. Des outils comme jq et les pipes shell fonctionnent naturellement avec.

json
// JSONL is ideal for:
//   - log files (one event per line)
//   - large datasets (streaming, append-only)
//   - machine learning training data
//   - database exports/imports
//   - append-only event streams

// Example: log entry per line
{"ts": "2024-01-15T10:00:00Z", "level": "info", "msg": "started"}
{"ts": "2024-01-15T10:00:01Z", "level": "error", "msg": "failed"}

// Tools: jq, xargs, awk | json.loads — all work line-by-line.

JSONL vs tableau JSON

Un tableau JSON enveloppe les enregistrements dans [ ] et exige de charger (ou de diffuser soigneusement) tout le fichier pour parser. JSONL place un enregistrement par ligne, permettant un vrai flux, un ajout facile et une récupération après lignes corrompues. Pour des jeux de données grands ou croissants, JSONL est presque toujours le meilleur choix.

json
// JSON Array (one big file):
[
  {"name": "Alice"},
  {"name": "Bob"},
  {"name": "Carol"}
]

// JSONL (one per line):
{"name": "Alice"}
{"name": "Bob"}
{"name": "Carol"}

// JSON Array: must load whole file to parse; hard to append.
// JSONL: streamable, appendable, resumable; slightly more
//        per-record overhead but far better for big files.
19

Sécurité

Risques JSONP

JSONP enveloppe le JSON dans un callback JavaScript pour qu'une balise <script> puisse récupérer des données cross-origin, contournant la politique same-origin. C'est dangereux : n'importe quel site peut lire la réponse, l'injection de callback permet le XSS, et les requêtes portent les cookies de la victime. Employez CORS à la place — JSONP est un héritage non sûr.

json
// JSONP (JSON with Padding) bypasses same-origin policy
// by wrapping JSON in a script callback:
callbackHandler({"secret": "data"});

// Loaded via <script src="https://api.example.com/data?callback=callbackHandler">

// RISKS:
//   - Any site can include the URL and read the response.
//   - XSS if the callback name is attacker-controlled.
//   - CSRF: the request is made with the victim's cookies.

// MODERN ALTERNATIVE: use CORS instead of JSONP.
// JSONP is legacy—avoid it for new APIs.

Prévention XSS

Le JSON intégré dans des balises HTML <script> peut causer du XSS : la chaîne '</script>' termine le script trop tôt. De plus, U+2028 et U+2029 (séparateurs de ligne/paragraphe) sont valides dans les chaînes JSON mais cassent JavaScript. Échappez <, >, &, U+2028, U+2029 en intégrant du JSON dans du HTML, ou employez une bibliothèque comme serialize-javascript.

json
// JSON itself is data, not executable—BUT embedding it in
// HTML can cause XSS if not careful.

// BAD: output JSON inside <script> without escaping:
//   <script>
//     var data = {"name": "</script><script>alert(1)</script>"};
//   </script>

// GOOD: escape < and > (and &) when embedding in HTML:
const safe = JSON.stringify(data)
  .replace(/</g, "\\u003c")
  .replace(/>/g, "\\u003e")
  .replace(/&/g, "\\u0026")
  .replace(/\u2028/g, "\\u2028")
  .replace(/\u2029/g, "\\u2029");

// Or use a library: js-xss, serialize-javascript.

Pollution de prototype

La pollution de prototype survient quand du JSON non fiable contenant des clés comme '__proto__' ou 'constructor' est fusionné dans des objets, empoisonnant Object.prototype et affectant tous les objets. Défenses : employez Object.create(null), bloquez les clés dangereuses, préférez Map pour les données non fiables, et gardez les bibliothèques de fusion à jour.

json
// Merging untrusted JSON into objects can pollute prototypes:
const evil = JSON.parse('{"__proto__": {"isAdmin": true}}');

// BAD merge (Object.assign does NOT pollute, but some libs do):
//   function merge(target, src) {
//     for (const k in src) target[k] = src[k];
//   }

// Attackers can set Object.prototype.isAdmin = true,
// affecting ALL objects.

// Defenses:
//   - Use Object.create(null) for parsed objects.
//   - Block keys like __proto__, constructor, prototype.
//   - Use Map instead of plain objects for untrusted data.
//   - Keep dependencies updated (some had merge() flaws).

Injection via JSON

JSON résiste à lui-même à l'injection, mais le construire par concaténation de chaînes est dangereux — l'entrée utilisateur peut sortir de la structure JSON. Employez toujours un vrai sérialiseur (JSON.stringify). Idem en aval : requêtes SQL paramétrées, execFile avec tableaux d'arguments, et moteurs de templates échappant le HTML.

json
// JSON itself is not injectable, but building JSON by
// concatenation is dangerous:

// BAD: string concatenation
//   const json = '{"name": "' + userInput + '"}';
//   // userInput = '"); drop table; //'  ->  breaks out

// GOOD: always use a real serializer
const json = JSON.stringify({ name: userInput });

// For SQL: use parameterized queries, not JSON interpolation.
// For shell: use execFile with arg arrays, not string concat.
// For HTML: use textContent or a templating engine that escapes.

DoS via JSON volumineux ou profond

DoS via JSON : d'énormes fichiers épuisent la RAM, une imbrication profonde fait déborder la pile du parseur, et des structures pathologiques (l'analogue JSON du « billion laughs ») gonflent une petite entrée. Défenses : plafonnez la taille du corps de requête au proxy, limitez la profondeur de parsing, employez des parseurs en flux pour les grandes entrées, et réglez des timeouts.

json
// Attackers can craft JSON to exhaust memory or CPU:
//
//   1. Huge file: 1 GB of '[1,1,1,...]' to exhaust RAM.
//   2. Deep nesting: '{"a":{"a":{"a":...}}}' (10000 levels)
//      to overflow the parser's stack.
//   3. 'Billion laughs': nested entity expansion (XML-era,
//      but JSON analogs exist with $ref in some libs).
//   4. Many keys: 10 million keys in one object.

// Defenses:
//   - Cap request body size at the server/reverse proxy.
//   - Limit parsing depth (Ajv, fast-json-parse options).
//   - Use streaming parsers (stream-json, oboe) for big input.
//   - Set timeouts on parsing.

Pratiques de parsing sûres

Parsing JSON sûr : employez toujours JSON.parse (jamais eval), validez contre un schéma (Ajv, jsonschema) avant usage, plafonnez profondeur et nombre de clés, désactivez les clés __proto__, et envisagez de parser les entrées non fiables dans un Web Worker ou un bac à sable. JSON.parse est lui-même à l'abri de l'exécution de code ; les risques viennent de l'usage des données parsées.

json
// 1. Validate with a schema before using untrusted JSON.
const Ajv = require("ajv");
const ajv = new Ajv({ allErrors: true });
const validate = ajv.compile(schema);
if (!validate(data)) throw new Error(ajv.errorsText(validate.errors));

// 2. Limit depth and key count when parsing.
// 3. Use reviver/replacer to coerce types safely.
// 4. Never eval() or Function('return ' + json) — use JSON.parse.
// 5. Disable dangerous features (e.g., __proto__ keys).
// 6. Parse untrusted JSON in a sandbox or worker if possible.

// JSON.parse is safe; eval is NOT.
20

Bonnes pratiques et outils

Schéma d'abord

Concevez les API schéma d'abord : définissez un JSON Schema, générez les types de langage depuis lui (typescript-json-schema, quicktype, jsonschema2pojo), et validez requêtes/réponses à l'exécution. Cela attrape tôt les violations de contrat, permet la génération de code et sert de documentation vivante.

json
// Define a JSON Schema before shipping an API.
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["id", "name"],
  "properties": {
    "id":   { "type": "integer" },
    "name": { "type": "string", "minLength": 1, "maxLength": 100 }
  },
  "additionalProperties": false
}

// Generate types from the schema (TypeScript, Java, Go, ...).
// Validate both requests and responses against the schema.
// Publish the schema for clients (OpenAPI, JSON Schema).

Nommage cohérent

Choisissez une convention de nommage pour les clés et appliquez-la de façon cohérente : camelCase (la plupart des API JSON et JS), snake_case (backends Python/Ruby, API Google), ou PascalCase (.NET). Mélanger les styles embrouille. Si le front et le back diffèrent, convertissez à une seule frontière plutôt que de mélanger dans le schéma.

json
// Pick ONE naming convention and apply it everywhere.

// camelCase (most JSON APIs, JavaScript ecosystem):
{ "firstName": "Alice", "lastName": "Smith" }

// snake_case (Python/Ruby backends, many Google APIs):
{ "first_name": "Alice", "last_name": "Smith" }

// kebab-case (rare in JSON, common in URLs/config):
{ "first-name": "Alice" }

// PascalCase (rare in JSON keys, common in C#/.NET types):
{ "FirstName": "Alice" }

// Avoid mixing; convert at the boundary if the front/back differ.

Versionnage

Versionnez les API dès le premier jour : dans le chemin d'URL (/v1/), un champ de version dans la charge utile, l'en-tête Accept (type média) ou un namespace (JSON-LD @context). Les changements additifs (nouveaux champs optionnels) sont généralement non cassants ; augmentez la version pour les champs retirés/renommés ou une sémantique changée.

json
// 1. Version in the URL path:
//    https://api.example.com/v1/users

// 2. Version field in the payload:
{ "version": "1.0", "data": { ... } }

// 3. Accept header / media type:
//    Accept: application/vnd.example.v1+json

// 4. Namespace the JSON (JSON-LD, JSON:API 'type'):
{ "@context": "https://schema.org/v1", ... }

// Plan for evolution: add optional fields freely, but bump
// the version for breaking changes (removed/renamed fields,
// changed semantics or types).

Encodage (UTF-8)

UTF-8 est l'encodage par défaut et le seul largement recommandé pour JSON. Enregistrez les fichiers en UTF-8 sans BOM (certains parseurs le gèrent mal), réglez Content-Type avec charset=utf-8, et Content-Length en octets. En Python, passez ensure_ascii=False pour garder les caractères Unicode lisibles au lieu d'échappements \uXXXX.

json
// Always use UTF-8 for JSON.
//   - Save files as UTF-8 (no BOM).
//   - Set Content-Type: application/json; charset=utf-8.
//   - Set Content-Length in bytes (not characters).

// In Node.js:
res.setHeader("Content-Type", "application/json; charset=utf-8");
res.end(JSON.stringify(data));

// In Python:
import json
with open("out.json", "w", encoding="utf-8") as f:
    json.dump(data, f, ensure_ascii=False)

// ensure_ascii=False keeps Unicode readable in the file.

Conseils de performance

Pour la performance : diffusez les grands JSON en flux (ijson, stream-json, streaming Jackson) au lieu de tout mettre en mémoire ; employez des sérialiseurs rapides (orjson, fast-json-stringify) ; transmettez compact et compressez en gzip/brotli par HTTP ; évitez l'imbrication profonde et les énormes tableaux ; mettez en cache les résultats parsés pour éviter de re-parser.

json
// 1. Stream large JSON instead of buffering it all.
//    - Node: stream-json, JSONStream
//    - Python: ijson
//    - Java: Jackson streaming API

// 2. Use a fast serializer:
//    - Node: fast-json-stringify (schema-based), orjson (Python)
//    - Compile serializers from a schema for hot paths.

// 3. Compact JSON for transmission; pretty only for humans.

// 4. Avoid deep nesting and huge arrays when possible.

// 5. Compress with gzip/brotli over HTTP (huge savings).

// 6. Cache parsed results; don't re-parse the same payload.

Outils et validateurs

Outils pour travailler le JSON : validateurs en ligne (jsonlint.com, jsonschemavalidator.net), outils CLI (jq pour requêter/formater, jsonschema pour valider), support éditeur (VS Code et JetBrains ont la validation JSON + schéma intégrée), et générateurs de code (quicktype génère des types TypeScript/Java/Go/etc. depuis JSON ou un schéma).

json
// Online validators:
//   - https://jsonlint.com
//   - https://jsonformatter.org
//   - https://www.jsonschemavalidator.net

// CLI tools:
//   - jq          (filter, query, format JSON on the command line)
//   - jaq         (Rust jq clone, faster)
//   - jsonschema  (Python CLI for schema validation)
//   - ajv         (Node CLI/library for JSON Schema)

// Editor support:
//   - VS Code: built-in JSON + schema validation
//   - JetBrains: built-in JSON + schema support
//   - vim/emacs: plugins available

// Schema tools:
//   - quicktype   (generate types from JSON)
//   - typescript-json-schema
//   - jsonschema2pojo (Java)

Was this helpful?

Learning path

Learn from scratch

Learn this language from the ground up with structured lessons.