Formater du JSON

La façon économique d’écrire un formateur consiste à parcourir les caractères et à ajouter un retour à la ligne après chaque accolade et chaque virgule. Cela fait cinquante lignes, cela marche sur la plupart des entrées, et cela échoue sur le seul cas qui compte : une accolade, un crochet ou une virgule à l’intérieur d’une chaîne. Une URL avec un query string, une expression régulière stockée comme réglage, un message contenant une virgule — et la sortie n’est plus du JSON valide.

Celui-ci fait passer le document par un vrai analyseur et imprime le résultat. Conséquence : tout ce qu’il rend est garanti analysable, et tout ce qu’il refuse l’est vraiment. Il n’existe pas de troisième état où un outil aurait à moitié compris l’entrée et produit quelque chose qui a l’air correct.

Analyser puis réimprimer n’est pas sans conséquences, et un outil qui ne le dirait pas les cacherait. Les nombres sont réécrits sous leur forme exacte la plus courte : `1.0` devient `1` et `1e3` devient `1000`. Les clés en double se réduisent à la dernière, parce que c’est ce que fait tout analyseur JSON. Les caractères échappés sans nécessité perdent leur barre oblique inverse.

Rien de tout cela ne change ce que le document signifie pour un analyseur, et c’est pourquoi c’est acceptable. Si vous avez besoin que les octets soient conservés à l’identique — vous signez le document, ou vous comparez une somme de contrôle — ne le formatez pas du tout, car tout formateur qui réindente a déjà changé les octets.

Deux systèmes qui sérialisent le même objet émettent souvent ses clés dans un ordre différent, et le diff qui en résulte fait la taille du fichier — ce qui rend impossible la relecture d’un changement d’un seul champ. Trier les deux côtés d’abord réduit le diff au changement lui-même.

Les tableaux sont volontairement laissés tranquilles. Un objet est non ordonné par définition et réordonner ses clés ne change rien ; un tableau est une séquence, et le trier change la donnée. Des outils qui trient les deux existent, et ils réordonnent en silence une liste d’étapes, une liste de coordonnées ou une liste de migrations.

Deux espaces est la convention du JSON dans la plupart des écosystèmes, et c’est ce que produisent `npm`, `composer` et la plupart des linters. Quatre apparaît dans les projets proches de Python, puisque cela correspond au langage. Une tabulation convient là où le fichier sera lu dans des éditeurs aux préférences différentes, puisque c’est alors le lecteur qui décide de sa largeur.

Le seul endroit où ce n’est pas une préférence, c’est un dépôt où un formateur est déjà configuré. Alignez-vous dessus : un fichier reformaté avec une autre indentation produit un diff qui touche chaque ligne, ce qui coûte à la relecture bien plus que l’indentation n’a jamais valu.

Un fichier contenant `//` n’est pas du JSON, et un fichier contenant une virgule finale non plus. Les deux sont du JSON5 ou du JSONC, des langages différents qui se ressemblent, et tous deux sont très employés dans les fichiers de configuration — `tsconfig.json` est du JSONC, ce qui surprend ceux qui essaient de le lire avec un analyseur strict.

Cette page les refuse au lieu de les faire disparaître, et c’est le comportement utile : elle vous dit que ce que vous tenez ne passera pas là où vous vous apprêtez à l’envoyer. Un formateur qui retirerait les commentaires en silence vous rendrait un fichier qui marche et un modèle mental qui ne marche pas.

Les nombres JSON deviennent des flottants double précision, et un double ne tient les entiers exactement que jusqu’à environ neuf millions de milliards. Au-delà, un identifiant est arrondi : un identifiant Snowflake, un ancien identifiant de statut, certaines clés primaires. `12345678901234567890` revient en `12345678901234567000`, et rien dans la sortie ne le signale.

Cette page le remarque et vous le dit, ce qui est le maximum de ce qu’elle peut faire. Le correctif est en amont : les systèmes qui émettent des identifiants au-delà de cette limite les envoient sous forme de chaînes précisément pour cela, et si le vôtre ne le fait pas, le formatage n’est pas l’étape où vous pouvez le réparer.

Un JSON produit par un système ancien écrit souvent `\u00e9` là où le vôtre écrit `é`. Les deux formes sont valides et signifient exactement la même chose ; l’échappement `\u` existe pour que le document survive à un canal qui ne serait pas propre en UTF-8. Cette page réimprime les caractères tels quels, parce que c’est ce qui se lit.

La conséquence est qu’un document français reformaté ici est plus court et plus lisible qu’à son arrivée, sans qu’aucune donnée n’ait changé. Si votre destination exige la forme échappée — un vieux service, un champ déclaré en ASCII — le formatage n’est pas l’endroit où la rétablir : c’est un réglage du sérialiseur qui produit le document.

Le tri est un ordre par point de code, pas un ordre alphabétique français. Concrètement, `zone` passe avant `échéance`, parce que `é` a un point de code supérieur à celui de toutes les lettres non accentuées. Ce n’est pas ce qu’un dictionnaire ferait, et c’est pourtant le bon comportement ici.

La raison est qu’un tri sert à rendre deux documents comparables, et que la comparaison doit être reproductible partout. Un tri sensible à la locale donnerait un ordre différent selon la machine, ce qui ferait réapparaître exactement le diff illisible que le tri devait supprimer.

Le reformatage se refait à chaque frappe, donc un document de plusieurs mégaoctets fait travailler l’onglet en continu. Cela reste utilisable, mais la latence devient perceptible autour de quelques mégaoctets, et elle dépend entièrement de votre machine puisque c’est elle qui calcule.

À cette taille, l’outil adapté est celui de votre éditeur, qui travaille sur le fichier plutôt que sur son contenu collé dans un champ. Cette page est faite pour ce qu’on a réellement sous la main : une réponse d’API, un bloc de configuration, un champ de journal — c’est-à-dire quelques dizaines de kilooctets au plus.