Chapitre 8.7Le JSON

Dans les chapitres sur REST et GraphQL, nous avons vu que les API échangent des données au format JSON. Mais qu'est-ce que c'est, exactement ?

C'est probablement le format de données que tu croiseras le plus souvent dans ta vie professionnelle, même sans écrire une ligne de code. Il apparaît dans les réponses d'API qu'un développeur te montre, dans les fichiers de configuration d'un outil, dans les exports d'un service tiers. Autant savoir le lire.

Le principe

JSON (JavaScript Object Notation) est un format texte pour représenter des données structurées. Il a été formalisé au début des années 2000 par Douglas Crockford, qui ne l'a pas inventé de zéro mais a mis par écrit une convention déjà utilisée par les développeurs JavaScript. Son objectif était d'offrir une alternative plus légère au XML, qui dominait alors les échanges de données.

Son grand mérite, c'est d'être lisible à la fois par les humains et par les machines. Tu n'as pas besoin d'outil spécialisé pour comprendre un fichier JSON, il suffit de l'ouvrir dans un éditeur de texte.

{
    "nom": "Dupont",
    "prenom": "Marie",
    "age": 32,
    "premium": true,
    "dateResiliation": null,
    "adresses": [
        {
            "ville": "Paris",
            "codePostal": "75001"
        },
        {
            "ville": "Lyon",
            "codePostal": "69001"
        }
    ]
}

Tout JSON se construit avec quelques briques seulement.

• Les objets : des paires clé-valeur entre accolades. Ici, "nom" est une clé et "Dupont" est sa valeur.
• Les tableaux : des listes ordonnées entre crochets. La clé "adresses" contient un tableau de deux objets.
• Les chaînes de texte : toujours entre guillemets doubles.
• Les nombres : sans guillemets, avec un point comme séparateur décimal (jamais une virgule à la française).
• Les booléens : true ou false, en minuscules, sans guillemets.
• La valeur nulle : null, qui signifie "cette information existe mais elle est vide". Ce n'est pas la même chose qu'une clé absente, et cette nuance provoque régulièrement des bugs.

Ces briques s'imbriquent librement. Un tableau peut contenir des objets, qui peuvent contenir d'autres tableaux, et ainsi de suite. C'est ce qui permet de représenter une commande complète, avec son client, ses lignes de produits et son adresse de livraison, dans un seul document.

Les règles du format

JSON est un format volontairement strict. Il n'y a pas d'ambiguïté possible, ce qui explique qu'il soit si facile à traiter par les machines. En contrepartie, la moindre entorse fait échouer la lecture du fichier entier, et pas seulement de la ligne fautive.

Voici les erreurs qui reviennent le plus souvent.

{
    nom: "Dupont",
    'prenom': 'Marie',
    "age": 32,
    "ville": "Paris",
}

• Clé sans guillemets : nom doit s'écrire "nom". En JavaScript on peut s'en passer, en JSON non.
• Guillemets simples : JSON n'accepte que les guillemets doubles, pour les clés comme pour les valeurs.
• Virgule finale : la virgule après la dernière paire (juste avant l'accolade fermante) est interdite. C'est probablement l'erreur la plus fréquente, et la plus agaçante.

Si un développeur te dit "ton fichier JSON est mal formé", ces trois points couvrent la grande majorité des cas. Des outils en ligne de validation (les "JSON linters") pointent la ligne fautive en une seconde.

Deux autres règles méritent d'être connues, car elles ont des conséquences concrètes.

D'abord, l'ordre des clés dans un objet n'a aucune signification. Deux documents qui listent les mêmes clés dans un ordre différent sont équivalents. Ne construis jamais un traitement qui suppose que "nom" arrive avant "prenom".

Ensuite, les nombres ont une limite de précision. La plupart des langages, JavaScript en tête, traitent les nombres JSON comme des nombres à virgule flottante et perdent en précision au-delà de 9 007 199 254 740 991 environ. Un identifiant très long ou un numéro de compte peuvent donc être silencieusement altérés. La parade classique consiste à transporter ces valeurs sous forme de texte, entre guillemets, puisqu'on ne fait de toute façon jamais de calcul avec un identifiant.

Pourquoi JSON a gagné

Avant JSON, le format dominant pour les échanges de données était le XML.

<utilisateur>
    <nom>Dupont</nom>
    <prenom>Marie</prenom>
    <age>32</age>
</utilisateur>

XML est nettement plus verbeux, car chaque donnée est entourée d'une balise ouvrante et d'une balise fermante qui répètent le même mot. Sur un gros volume d'échanges, cette redondance finit par coûter en bande passante, et surtout elle rend la lecture plus pénible pour un humain.

JSON s'est imposé avec l'essor du JavaScript et des API web. Un navigateur pouvait consommer du JSON quasiment sans effort, là où le XML demandait une couche de transformation. Aujourd'hui, c'est le format par défaut des échanges sur le web.

Cela dit, XML n'est pas mort. Il reste très présent dans les échanges bancaires, la facturation électronique, les flux RSS, les documents bureautiques et tous les secteurs où l'on a besoin de valider finement la structure d'un document. Il propose des mécanismes de validation et de transformation que JSON a mis des années à rattraper.

JSON au quotidien

Tu le rencontreras dans quatre contextes principaux.

• Les réponses d'API : un serveur qui répond en JSON annonce Content-Type: application/json dans les en-têtes de sa réponse HTTP. C'est le cas de la quasi-totalité des API publiques modernes.
• Les fichiers de configuration : package.json pour un projet Node.js, tsconfig.json pour TypeScript, composer.json pour PHP. Le nom du fichier trahit son format.
• Le stockage : les bases de données orientées documents comme MongoDB manipulent des documents dont la structure ressemble beaucoup à du JSON. Les bases relationnelles comme PostgreSQL savent elles aussi stocker et interroger des colonnes JSON.
• Les exports de données : beaucoup de services proposent d'exporter un historique ou un catalogue en JSON, souvent au format JSON Lines (un document JSON complet par ligne de fichier), qui permet de traiter un gros volume ligne par ligne sans tout charger en mémoire.

Pour figer ce contrat, il existe JSON Schema, un standard qui permet de décrire la structure attendue d'un document JSON (quelles clés sont obligatoires, quels types sont autorisés, quelles valeurs sont acceptables) et de vérifier automatiquement qu'un document la respecte. C'est très utile dès que plusieurs équipes ou plusieurs entreprises échangent des fichiers.

Les limites

JSON n'est pas parfait, et ses défauts sont le revers direct de sa simplicité.

• Pas de commentaires : impossible d'ajouter une note explicative dans un fichier JSON standard. Pour un fichier de configuration que des humains éditent à la main, c'est un vrai manque. D'où l'apparition de variantes tolérantes comme JSON5 ou JSONC, et le succès de YAML sur ce terrain.
• Pas de dates : JSON ne connaît ni date, ni heure, ni durée. La convention établie consiste à écrire les dates en texte au format ISO 8601, par exemple "2025-03-14T09:30:00Z", et à les reconvertir côté application. Nous en parlons dans le chapitre sur les formats de date.
• Pas de données binaires : une image ou un fichier ne se glissent pas directement dans du JSON. Il faut les encoder en texte, ce qui alourdit le résultat d'environ un tiers, ou les transmettre séparément.
• Un poids non négligeable : chaque clé est répétée en toutes lettres dans chaque objet du tableau. Pour des échanges massifs entre serveurs, des formats binaires comme Protocol Buffers (créé par Google) ou MessagePack sont plus compacts et plus rapides à traiter, au prix d'une lisibilité nulle pour un humain.

Un dernier piège, cette fois côté sécurité. Un document JSON reçu de l'extérieur reste une donnée non fiable, qu'il faut valider avant utilisation. Un JSON très profondément imbriqué ou très volumineux peut aussi servir à saturer un serveur, raison pour laquelle on impose généralement une taille maximale aux requêtes entrantes.

Les formats voisins

Trois formats reviennent souvent dans les discussions et méritent d'être situés.

• YAML : pensé pour être écrit par des humains, il se passe d'accolades et de guillemets et repose sur l'indentation. Il accepte les commentaires, ce qui explique son omniprésence dans les fichiers de configuration des outils de déploiement. Sa sensibilité à l'indentation en fait aussi une source d'erreurs classique.
• TOML : une alternative à YAML, plus rigide et moins piégeuse, très utilisée dans les écosystèmes Rust et Python.
• CSV : le bon vieux tableau à colonnes séparées par des virgules. Imbattable pour des données parfaitement tabulaires que l'on veut ouvrir dans un tableur, mais incapable de représenter une structure imbriquée.

Aucun de ces formats ne remplace JSON pour les échanges entre machines. Ils occupent des niches où sa rigidité devient un handicap.

Malgré ses limites, la simplicité de JSON en fait le format universel de l'échange de données. Si tu travailles dans la tech, tu en liras tous les jours, et savoir repérer une accolade mal fermée te fera gagner un aller-retour avec l'équipe technique.