Qu’est-ce qu’un fichier JSON ?

JSON est un format texte que n’importe quel éditeur ouvre. Il est utilisé pour l’échange entre programmes et le web.

L’extension est .json et le nom complet JavaScript Object Notation. L’un et l’autre comptent moins que ce que le fichier peut contenir, et c’est le sujet du reste de cette page.

Il remonte à 2001. La spécification est RFC 8259.

L’âge est utile à connaître pour une raison pratique : plus un format est ancien, plus les programmes ont eu le temps de l’apprendre.

Elle est publiée intégralement : n’importe qui peut l’implémenter à partir du document plutôt qu’en l’observant, et c’est pourquoi ce format apparaît dans tant de programmes et pourquoi des fichiers écrits il y a vingt ans s’ouvrent encore. Une spécification publiée n’est pas pour autant libre de redevances : quand un format enveloppe un codec, les brevets sont une question à part, que la norme ne tranche pas.

JSON enregistre son contenu à l’identique. Le réenregistrer ne change rien : vous pouvez l’ouvrir, le modifier et le réenregistrer autant de fois que vous voulez sans accumuler de dégâts, et c’est ce qui en fait un format de travail plutôt qu’un format de livraison.

JSON n’a pas de syntaxe de commentaires. Tout ce qui explique doit vivre hors du fichier, ce qui est bon à savoir avant de le choisir pour quelque chose qu’un humain modifiera à la main.

Visual Studio Code, jq et Postman le lisent, comme la plupart des programmes du même genre.

Quand un fichier ne s’ouvre pas, le format est rarement en cause : le plus souvent, c’est le programme qui est plus ancien que lui. Convertir vers quelque chose de plus ancien est le contournement fiable, et c’est à cela que sert le reste de ce site.

Tous les navigateurs actuels le lisent.

Vous pouvez donc le poser sur une page ou l’attacher à un message sans vous demander ce que le destinataire a installé.

JSON est fait pour être ouvert et modifié. Gardez le fichier dans ce format tant que le travail dure, et exportez depuis lui chaque fois qu’une version finie est nécessaire.

Un document JSON est construit à partir d’objets, de tableaux, de chaînes, de nombres, de booléens et de null. C’est le vocabulaire entier, et la brièveté de la liste est la raison pour laquelle le format a pris le dessus : tous les langages de programmation ont déjà ces six-là, donc lire un document revient à appeler une fonction et à récupérer des valeurs natives sans rien à mapper.

La spécification tient en quelques pages. Elle a été décrite plutôt que conçue — Douglas Crockford a pris la syntaxe littérale d’objet que JavaScript avait déjà et a mis par écrit ce qui fonctionnait déjà — ce qui explique pourquoi elle semble évidente plutôt qu’ingénieuse. Le format a été standardisé sous la RFC 8259 en 2017, et c’est aujourd’hui le format d’échange de données par défaut du web.

JSON n’a pas de commentaires, délibérément, et c’est la propriété du format dont on se plaint le plus. Le raisonnement était que les commentaires invitent des directives de parsing, et le résultat est que JSON est un mauvais langage de configuration aussi bon soit-il comme format d’échange.

Trois contournements circulent. Une clé appelée quelque chose comme un commentaire-souligné, que tout parseur acceptera et que tout validateur de schéma rejettera. JSON5 et JSONC, qui ajoutent les commentaires et les virgules traînantes et qui ne sont pas du JSON — le fichier de paramètres de Visual Studio Code est du JSONC, ce qui explique pourquoi le modifier dans un outil strict échoue. Et la réponse honnête, qui est d’utiliser TOML ou YAML pour tout ce qu’une personne maintient.

JSON ne distingue pas les entiers de la virgule flottante. La plupart des parseurs lisent chaque nombre comme un double IEEE 754, et un double ne tient les entiers de façon exacte que jusqu’à environ neuf trillions (2^53).

Au-delà, les valeurs changent en silence. Un identifiant de base de données 64 bits, un identifiant de type snowflake de Twitter, un montant financier important dans la plus petite unité (centimes d’euro) — tous peuvent revenir comme un nombre différent de celui qui a été envoyé, sans erreur nulle part. Le remède est d’envoyer ces valeurs sous forme de chaînes, ce que fait toute API sérieuse, et cela vaut la peine d’être vérifié plutôt que supposé lors d’une intégration avec une qui pourrait ne pas le faire.

Les clés en double ne sont pas interdites. Les parseurs diffèrent dans ce qu’ils en font — la plupart gardent la dernière, certains gardent la première, quelques-uns signalent une erreur — et un document qui s’appuie sur l’un ou l’autre comportement s’appuie sur une implémentation plutôt que sur JSON.

L’ordre des clés n’est pas non plus garanti comme préservé, donc traiter un objet comme une structure ordonnée est une erreur ; utilisez un tableau si l’ordre compte. Et il n’y a pas de dates : la convention universelle est les chaînes ISO 8601 (« 2026-03-15T14:30:00Z »), et tout parseur vous tend une chaîne qu’autre chose doit interpréter.

JSON est en UTF-8. La spécification le dit pour tout ce qui s’échange entre systèmes, et le corollaire pratique est qu’une marque d’ordre d’octet n’est pas autorisée — ces trois octets invisibles au début d’un fichier provoquent une erreur d’analyse dont le message blame en général le premier caractère plutôt que de nommer la cause.

Si un fichier JSON échoue à l’analyse et a l’air parfait dans un éditeur, c’est la première chose à vérifier. « UTF-8 sans BOM » est le réglage, et c’est le même conseil que pour tous les autres formats texte de ce site, avec la différence qu’ici c’est réellement fatal plutôt qu’agaçant.

Un document JSON doit être complet avant de pouvoir être analysé — le crochet fermant est ce qui le rend valide — donc un tableau de dix gigaoctets d’enregistrements doit être lu entièrement en mémoire avant que le premier ne soit disponible. Pour de grands exports et des pipelines de logs, c’est fatal.

NDJSON, aussi appelé JSON Lines, le résout en mettant un objet JSON complet par ligne, sans tableau autour. Chaque ligne s’analyse indépendamment, donc un fichier de n’importe quelle taille streame enregistrement par enregistrement, et un processus peut commencer à travailler sur le premier enregistrement immédiatement. Les exports de données, l’expédition de logs et les jeux de données d’apprentissage automatique l’utilisent presque tous, et c’est le format vers lequel tendre dès qu’un fichier JSON se mesure en gigaoctets.

JSON Schema est la façon standard de décrire à quoi ressemble un document valide, et cela vaut la peine d’être utilisé pour toute interface entre deux systèmes — cela transforme « l’API a renvoyé quelque chose de bizarre » en une erreur précise qui nomme le champ. La prise en charge est bonne et moins uniforme que l’équivalent XML.

Pour le travail quotidien, un éditeur avec prise en charge de JSON vous donne gratuitement la moitié importante : une virgule manquante ou en trop est signalée à sa place, et du JSON généré par machine arrivé en une longue ligne peut être joliment imprimé en quelque chose de lisible. Les deux sont des opérations de deux secondes qui économisent une quantité surprenante de temps.

Une fois qu’un document a une structure identifiée, le besoin suivant est de la modifier sans tout réécrire. JSON Pointer (RFC 6901) décrit un chemin à l’intérieur d’un document — `/users/3/email` pointe vers le quatrième utilisateur, son champ email — et JSON Patch (RFC 6902) décrit des opérations ciblées sur ce chemin : ajouter, retirer, remplacer, déplacer, copier, tester.

Ces deux standards sont la base de l’API PATCH en HTTP et de beaucoup d’outils de configuration déclarative (kubectl pour Kubernetes, par exemple). Ils valent la peine d’être connus pour quiconque touche à des API modernes, et un validateur JSON Schema qui connaît aussi JSON Pointer ferme la boucle entre décrire la structure et la modifier sans erreur.