Formateur JSON

Formater du JSON, c’est ajouter les espaces dont un humain a besoin et dont une machine se passe : un membre par ligne, une indentation cohérente, une espace après chaque deux-points. Les données ne changent pas. Seule leur présentation change.

Ce qu’il est facile de rater, c’est précisément cette dernière phrase. Un formateur qui analyse votre document en valeurs JavaScript puis les re-sérialise a déjà réécrit vos nombres avant d’afficher quoi que ce soit, et la plupart font exactement cela.

Ce que le formatage ne change pas

Ce formateur réémet les jetons qu’il a lus au lieu de re-sérialiser des valeurs analysées. Le texte de chaque nombre, chaîne et littéral revient donc octet pour octet, et seuls les espaces qui les séparent sont réécrits.

Cela compte plus qu’il n’y paraît. Passez un document contenant un identifiant de 19 chiffres dans un formateur bâti sur JSON.parse et JSON.stringify, et l’identifiant revient différent, silencieusement, sans le moindre avertissement dans l’interface.

Les nombres gardent leur texte exact

1.50 reste 1.50, 1e3 reste 1e3, -0 reste -0, et 12345678901234567890 reste lui-même au lieu de devenir 12345678901234567000.

Les chaînes sont copiées telles quelles

Un \u00e9 échappé reste échappé et un é littéral reste littéral. Le formatage n’est pas le moment de décider comment une chaîne doit être encodée, et il ne le décide donc pas.

L’ordre des clés est préservé

Sauf si vous activez explicitement le tri. Les objets JSON ne sont pas ordonnés d’après la spécification, mais en pratique tous les analyseurs conservent l’ordre d’insertion et les diffs en dépendent.

Les clés en double sont conservées et signalées

En supprimer une changerait ce que voit le consommateur du document. Vous recevez à la place un avertissement qui nomme les deux positions.

Quelle indentation choisir

Deux espaces est la valeur par défaut ici parce que c’est ce qu’émettent npm, Prettier et la quasi-totalité de l’outillage JavaScript, et parce que l’imbrication en JSON devient vite profonde. Quatre espaces se lisent mieux sur des fichiers de configuration peu imbriqués. Les tabulations laissent chaque lecteur choisir sa largeur, ce qui est l’argument d’accessibilité en leur faveur, et elles se compressent légèrement mieux.

Pour tout ce qui est transmis plutôt que lu, minifiez. Les espaces dans une réponse JSON sont un pur surcoût, et sur un payload d’API typique ils représentent entre 10 et 20 pour cent des octets.

Fins de ligne et saut de ligne final

La sortie utilise LF par défaut. Une option CRLF existe parce que l’outillage Windows et certains systèmes d’intégration continue y sont sensibles, et parce qu’un fichier qui mélange les deux produit un diff où toutes les lignes semblent modifiées.

Les espaces hors des chaînes n’ont aucune signification pour un analyseur, donc rien de tout cela n’affecte la validité. Cela affecte vos diffs, ce qui est en pratique ce que vous remarquez.

How to do this in code

La même opération en code. Toutes ces variantes produisent une indentation de deux espaces ; toutes réécriront également vos nombres, ce qui est le compromis que vous acceptez quand le payload ne contient pas de grands entiers.

const pretty = JSON.stringify(JSON.parse(text), null, 2);

// Tabs
const tabbed = JSON.stringify(JSON.parse(text), null, '\t');

import json

pretty = json.dumps(json.loads(text), indent=2)

# Keep non-ASCII readable rather than escaping it
pretty = json.dumps(json.loads(text), indent=2, ensure_ascii=False)

# From the command line
# python -m json.tool --indent 2 input.json

jq . input.json              # 2 spaces, the default
jq --indent 4 . input.json
jq --tab . input.json
jq -c . input.json           # compact

var buf bytes.Buffer
if err := json.Indent(&buf, data, "", "  "); err != nil {
    return err
}

// json.Indent works on raw bytes, so unlike Unmarshal it does
// not touch your numbers at all.

require 'json'

pretty = JSON.pretty_generate(JSON.parse(text))

$pretty = json_encode(
    json_decode($text),
    JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE
);

Questions fréquentes

Y a-t-il une limite de taille ?

Aucune limite n’est imposée par cette page. Le plafond réel est votre navigateur : un moteur JavaScript limite une chaîne unique à environ 512 Mo, donc rien de plus gros ne peut même être conservé en mémoire. Formater un document de 10 Mo demande ici environ 780 millisecondes de travail, exécutées dans un worker en arrière-plan pour que la page reste réactive.

Le formatage modifie-t-il mes données ?

Non. Les espaces hors des chaînes n’ont aucun sens en JSON, et ce formateur réémet chaque valeur exactement telle que vous l’avez écrite au lieu de l’analyser puis de la re-sérialiser. Activer le tri des clés modifie en revanche le document, et c’est pour cela qu’il est désactivé par défaut.

Pourquoi mon fichier formaté diffère-t-il de celui que produit mon éditeur ?

Le plus souvent, il s’agit du saut de ligne final ou du style des tableaux d’objets. Certains formateurs laissent les tableaux courts sur une seule ligne ; celui-ci est cohérent, ce qui produit plus de lignes mais des diffs bien plus lisibles.