Formateur JSON

Ce que fait ce formateur JSON

JSON (JavaScript Object Notation) est le format le plus courant pour déplacer des données structurées entre programmes : réponses d’API, fichiers de configuration, lignes de journal, etc. Il est conçu pour être compact, ce qui le rend aussi difficile à lire dès que les objets s’imbriquent sur quelques niveaux ou arrivent sur une seule ligne. Cet outil prend tout JSON que vous collez et le réécrit de deux façons : embelli, avec une indentation cohérente pour que la structure saute aux yeux, ou minifié, débarrassé de chaque espace facultatif pour être aussi petit que possible à l’envoi.

Il valide aussi pendant le formatage. Comme il analyse le texte avant de le re-sérialiser, un JSON invalide ne produit jamais de sortie trompeuse — vous obtenez à la place la ligne et la colonne où l’analyse a échoué, dès lors qu’il peut les déduire, pour aller droit au problème.

Embellir vs. minifier : quand utiliser chacun

Les deux modes ont des objectifs opposés, et la plupart des flux de travail utilisent les deux à différentes étapes :

• Embellissez quand vous lisez ou déboguez : inspecter une réponse d’API, comparer deux payloads ou relire un fichier de configuration dans une pull request. L’indentation transforme un mur de texte en un arbre navigable.
• Minifiez quand vous expédiez : intégrer du JSON dans du HTML, le stocker dans un cookie ou un cache, ou l’envoyer dans le corps d’une requête où chaque octet compte. Le JSON minifié, ce sont exactement les mêmes données, sans les espaces.

Le sélecteur d’indentation (2 espaces, 4 espaces ou tabulation) n’affecte que la sortie embellie. Deux espaces est la convention la plus répandue en JavaScript et dans l’outillage web ; quatre espaces ou des tabulations conviennent aux équipes qui les préfèrent. Quel que soit votre choix, le résultat reste du JSON valide — l’indentation est purement cosmétique.

Lire les erreurs de validation

Quand le JSON est invalide, l’outil signale la ligne et la colonne du premier problème plutôt qu’un simple « invalide », sauf dans le seul cas que décrit la section sur l’endroit où pointent la ligne et la colonne. Les messages d’erreur des moteurs diffèrent d’un navigateur à l’autre et omettent souvent la position, aussi l’emplacement est-il calculé indépendamment et désigne un point raisonnable pour commencer. Corrigez la première erreur et revérifiez : un seul caractère égaré se transforme souvent en plusieurs problèmes apparents.

Erreurs JSON courantes

JSON est plus strict que les littéraux d’objet JavaScript auxquels il ressemble. Voici les erreurs qui piègent le plus :

• Virgules finales : une virgule après le dernier élément d’un objet ou d’un tableau est valide en JavaScript mais pas en JSON.
• Guillemets simples : les chaînes et les clés JSON doivent utiliser des guillemets doubles. 'valeur' est invalide ; "valeur" est correct.
• Clés sans guillemets : chaque clé d’objet doit être une chaîne entre guillemets, donc { name: "x" } doit devenir { "name": "x" }.
• Commentaires : JSON n’a pas de syntaxe de commentaire. // et /* */ provoqueront une erreur d’analyse.
• Nombres spéciaux : NaN, Infinity et -Infinity ne sont pas des nombres JSON valides.
• Mauvais guillemets : les « guillemets typographiques » collés depuis un traitement de texte ressemblent à des guillemets mais sont des caractères différents et ne seront pas analysés.

Où pointent la ligne et la colonne signalées

La position n’est pas là où vous avez omis quelque chose : c’est là où l’analyseur a rencontré pour la première fois quelque chose qui ne peut légalement pas s’y trouver, et ce sont d’ordinaire deux endroits différents. Dans l’objet ci-dessous, il manque à la ligne 3 la virgule qui devrait la clore — et l’outil signale la ligne 4, colonne 3 : le guillemet ouvrant de la clé suivante. Rien n’était fautif avant l’arrivée de ce guillemet, car le document aurait pu légalement se terminer après la ligne 3 ; l’analyseur n’apprend donc l’omission qu’en rencontrant quelque chose qui n’est ni une virgule ni une accolade fermante.

{
  "id": 42,
  "name": "widget"
  "price": 9.99
}

• Une virgule manquante est signalée au premier caractère de ce qui vient ensuite, ce qui dans du JSON indenté comme ci-dessus est la ligne suivante : lisez la ligne nommée avec celle du dessus.
• Une virgule superflue est signalée à l’accolade ou au crochet fermant : ligne 3, colonne 1 pour un objet dont la dernière paire est à la ligne 2. La virgule promet une paire de plus et l’accolade est ce qui rompt la promesse.
• Une chaîne non fermée est le plus souvent signalée à la fin de la ligne où elle s’est ouverte plutôt qu’au guillemet ouvrant, car le guillemet suivant sur une ligne ultérieure peut la fermer ailleurs. Un saut de ligne ne peut pas figurer dans une chaîne JSON, donc le saut est le premier caractère qui ne peut pas s’y trouver.
• Ligne 1, colonne 1 sur un document qui paraît parfait signifie le plus souvent une marque d’ordre des octets. Certains éditeurs en écrivent une en enregistrant en UTF-8 ; elle est invisible, elle précède l’accolade ouvrante, et JSON n’a pas de place pour elle.

Et là où l’outil ne peut déduire aucune position, il signale l’échec sans elle au lieu de nommer une coordonnée devinée. Une ligne et une colonne données avec assurance mais pointant vers une syntaxe parfaitement correcte vous feraient chercher au mauvais endroit, ce qui est pire que de savoir seulement que le document ne s’analyse pas.

Ce que le formatage change et ce qu’il conserve

Pour presque tout document, la réponse est l’espace blanc et rien d’autre. Mais l’outil ne modifie pas votre texte : il l’analyse en vraies valeurs et réécrit ces valeurs, et cinq choses ne survivent pas à cet aller-retour. Aucune n’est un défaut de l’outil — chacune est ce que la spécification JSON dit qu’est un nombre ou un objet — et chacune mérite d’être connue avant de coller la sortie par-dessus votre original.

• La même clé écrite deux fois : seule la dernière des deux survit, car un objet ne peut pas porter deux fois une clé. La RFC 8259 dit qu’un logiciel recevant un objet à noms dupliqués se comporte de façon imprévisible, et un autre analyseur peut garder le premier, donc laquelle des deux vous reste n’est pas non plus une chose sur laquelle compter.
• Un entier de plus de quinze chiffres : les nombres JSON sont lus en virgule flottante double précision, qui contient exactement tout entier jusqu’à deux puissance cinquante-trois — un nombre de seize chiffres — de sorte qu’un entier de quinze chiffres survit toujours et qu’un plus long peut ne pas survivre. Collez 12345678901234567890 et 12345678901234567000 ressort. Les longs identifiants de base de données sont la victime habituelle : gardez-les en chaînes si vous pouvez.
• Les formes à exposant et à zéros finaux sont normalisées : 1e3 revient en 1000, et 1.50 en 1.5. C’est le même nombre écrit de la façon standard.
• Une grandeur hors de ce que ce format admet revient sous une autre forme : 1e400 n’a pas de valeur en double précision et revient en null, et 1e-400 revient en 0. Une longue fraction décimale est arrondie à la précision dont le format dispose, exactement comme un long entier.
• Une séquence d’échappement devient le caractère qu’elle désigne : \u00e9 revient en é, et une paire de substitution échappée en l’émoji qu’elle épelle. Pour tout analyseur ce sont la même chaîne ; l’une des deux écritures est simplement plus courte.

L’ordre des clés est conservé tel que vous l’avez écrit, avec une exception qui mérite d’être connue : une clé faite uniquement de chiffres, qui se lit comme un entier positif ou nul tout simple inférieur à quatre milliards environ, est traitée comme un indice de tableau et revient au début de son objet dans l’ordre numérique, où que vous l’ayez mise. Rien d’autre ne bouge : aucune autre clé n’est réordonnée, et aucune n’est ajoutée ni renommée. Si quelque chose de tout cela vous importe, minifiez plutôt qu’embellir et comparez le résultat à votre original caractère par caractère. C’est le plus court chemin pour voir ce que l’aller-retour a fait.

Quand le JSON que vous cherchez est dans une chaîne

Les journaux de webhooks, les files de messages et les colonnes de base de données portent très souvent un document JSON entier comme une seule valeur de chaîne, chaque guillemet intérieur échappé. Le document extérieur est parfaitement valide, donc l’outil l’embellit et le signale valide — et la partie que vous veniez lire reste une longue ligne de barres obliques inverses. Rien n’a échoué : ce sont deux documents, l’un enveloppé dans une chaîne de l’autre.

{
  "event": "order.created",
  "payload": "{\"id\":42,\"total\":19.99}"
}

Le lire demande donc deux passes. Formatez ici le document extérieur, copiez ce qui se trouve entre les guillemets de la chaîne voulue, défaites l’échappement et recollez le résultat. L’outil Échappement de chaînes JSON fait cette étape intermédiaire : son sens inverse retransforme \" en " et la ligne en un document que cette page peut formater. Si vous maîtrisez ce qui a produit le fichier, le meilleur correctif est en amont — envoyez la charge utile comme objet imbriqué plutôt que comme chaîne, et aucune passe n’est nécessaire.

Un objet par ligne n’est pas un document

Les fichiers de journal, les exports d’API et les points de terminaison en flux contiennent couramment un objet JSON complet par ligne ; le format s’appelle JSON Lines, ou NDJSON. Chaque ligne est du JSON valide à elle seule, mais le fichier n’est pas un document JSON, car un document JSON contient exactement une valeur de premier niveau et celui-ci en contient plusieurs, l’une après l’autre, sans rien qui les relie.

{"level":"info","msg":"started"}
{"level":"warn","msg":"retrying"}
{"level":"error","msg":"gave up"}

Collez cela ici et l’outil signale la ligne 2, colonne 1 : le premier objet s’est terminé proprement, puis un second a commencé là où le document aurait dû finir. Deux voies s’offrent alors. Formatez une ligne à la fois, ce que vous voulez quand vous lisez une seule entrée de journal. Ou faites du fichier un seul document — enveloppez les lignes dans des crochets et mettez une virgule au bout de chaque ligne sauf la dernière — ce que vous voulez quand vous allez charger le tout dans quelque chose qui attend un tableau.