Meilleures pratiques de formatage JSON — indentation, lisibilité et les débats qui ne meurent pas

La grammaire de JSON est minimale. Six types de valeurs, pas de commentaires, pas de virgules finales, pas de flexibilité dans la façon dont les chaînes sont citées. Cette rigidité est sa force pour les machines et sa faiblesse pour les humains. Quand un humain doit lire ou écrire JSON — dans un fichier de configuration, une réponse API, un diff — le formatage compte.

Cet article couvre chaque décision de formatage que vous rencontrerez, ce que l’écosystème a décidé, et où les débats font encore rage.

Indentation : 2 espaces est le gagnant

La guerre Tabulations vs Espaces a un gagnant dans le monde JSON : 2 espaces. Presque chaque guide de style, linter et formateur par défaut utilise l’indentation de 2 espaces :

• Guide de style JSON Google — 2 espaces
• Prettier — 2 espaces (par défaut)
• ESLint — 2 espaces (la plupart des configurations)
• AWS CloudFormation — 2 espaces
• Manifestes Kubernetes — 2 espaces

La raison est pratique : JSON est déjà verbeux avec ses guillemets et accolades. L’indentation de 4 espaces pousse les objets imbriqués hors du bord droit de la plupart des éditeurs. 2 espaces maintient les choses lisibles sans gaspiller l’espace horizontal.

Utilisez 4 espaces si votre équipe préfère et si vous êtes cohérent. Utilisez des tabulations si vous devez, mais sachez que la plupart des outils JSON supposent des espaces, et l’indentation mélangée dans un fichier JSON est une erreur d’analyse en attente.

Virgules finales : toujours non

JSON ne permet pas les virgules finales. C’est l’erreur de syntaxe la plus courante dans les fichiers JSON édités à la main. Vous écrivez :

{
  "name": "Alice",
  "items": ["a", "b",],
}

Et un analyseur strict le rejette. La virgule finale après "b" et la virgule finale après l’accolade fermante } sont toutes deux illégales.

YAML permet les virgules finales (et la plupart des langages le font). JSON ne le fait pas. Si vos outils supportent JSONC (JSON avec Commentaires, utilisé dans tsconfig.json et settings.json de VS Code), les virgules finales sont autorisées. Mais le JSON pur — le type qui circule via les APIs — ne les tolère pas.

La meilleure défense : utilisez un formateur qui détecte cela automatiquement. Collez votre JSON dans un validateur avant de commiter.

Joli vs compact

Le JSON joli a des sauts de ligne et de l’indentation. Il est lisible, diffable et débogable :

{
  "status": "ok",
  "count": 42
}

Le JSON compact n’a pas d’espace blanc entre les tokens. Il est plus petit sur le réseau :

{"status":"ok","count":42}

La règle pratique :

• Destiné aux humains (fichiers de configuration, journaux, réponses API pendant le débogage) → joli.
• Destiné aux machines (payloads API en production, files d’attente de messages, flux d’événements) → compact.
• Stockage (bases de données, caches) → compact, sauf si vous devez le lire manuellement pendant le débogage.

Le JSON compact économise environ 20-30% en taille par rapport au JSON joli de 2 espaces. Pour un payload de 10 Ko, c’est 2-3 Ko. Sur des millions de requêtes, cela s’additionne. Pour un fichier de configuration que vous éditez à la main, la lisibilité du JSON joli vaut les octets supplémentaires.

Clés triées

Les clés d’objet doivent-elles être triées alphabétiquement ?

Pour : les diffs sont déterministes. Si vous ajoutez une clé, seule cette ligne apparaît dans un diff git. Sans clés triées, insérer une clé au milieu peut décaler chaque clé suivante, créant un diff bruyant.

Contre : le regroupement logique est plus lisible. Mettre "name" en premier et "id" en second est intuitif. Le tri alphabétique met "address" avant "name" sans raison sémantique.

La réponse pragmatique : triez les clés dans le JSON généré par machine (APIs, configs, diffs). Gardez l’ordre logique dans le JSON écrit à la main. La plupart des formatteurs (Prettier, jq, python -m json.tool) ont un indicateur --sort-keys que vous pouvez activer dans le CI.

Conventions de nommage des clés

Les clés de JSON sont des chaînes, et l’écosystème s’est accordé sur deux conventions :

• camelCase — le défaut JavaScript/Node.js. firstName, lastName, createdAt.
• snake_case — le défaut Python/Ruby/Rust. first_name, last_name, created_at.
• kebab-case — rare en JSON, plus courant dans les URLs et CSS. À éviter pour les clés d’API.

Choisissez-en une et tenez-vous-y. La plupart des APIs utilisent camelCase. Si vous construisez une API REST pour des consommateurs JavaScript, camelCase est le chemin de moindre résistance. Si vous interférez avec des services Python, snake_case réduit les frictions.

Le pire que vous puissiez faire est de les mélanger : firstName dans un endpoint, last_name dans un autre. Choisissez une convention, imposez-la avec un linter, et passez à autre chose.

Formatage des nombres

JSON ne distingue pas les entiers des flottants. 42 et 42.0 sont tous deux valides, et la plupart des analyseurs les traitent de la même façon. Mais le formatage compte pour la lisibilité :

• Entiers : pas de point décimal. 42, pas 42.0.
• Flottants : utilisez autant de chiffres que nécessaire. 3.14159, pas 3.14159000000000.
• Grands nombres : utilisez la notation scientifique si le nombre est énorme. 1e10 est plus clair que 10000000000.

JSON ne supporte pas Infinity, -Infinity ou NaN. Si votre langage sérialise ceux-ci, la sortie n’est pas du JSON valide et les analyseurs le rejetteront.

Chaînes : guillemets simples vs doubles

JSON exige des guillemets doubles pour les chaînes. Ce n’est pas négociable. 'hello' n’est pas du JSON valide. "hello" l’est.

Si votre linter ou éditeur permet les guillemets simples dans les fichiers JSON, il analyse du JSONC ou un sur-ensemble, pas du JSON standard. Les APIs et analyseurs qui s’attendent à du JSON strict rejetteront les chaînes à guillemets simples.

Commentaires : toujours pas autorisés

JSON n’a pas de syntaxe de commentaires. C’est par conception (la spécification dit que JSON est « un format d’échange de données », pas un langage de configuration), mais c’est la plainte la plus courante des développeurs qui utilisent YAML.

Solutions de contournement :

• Utilisez une clé "comment" ou "_comment". C’est laid mais valide.
• Utilisez JSONC (le format de VS Code) si vos outils le supportent.
• Passez à YAML ou TOML pour les fichiers de configuration où les commentaires comptent.

Le workflow du formateur

Le meilleur workflow pour le formatage JSON :

1. Écrivez JSON comme vous voulez. Ne perdez pas de temps à indenter à la main.
2. Exécutez un formateur à la sauvegarde. Prettier, jq, ou le formateur intégré de votre éditeur.
3. Commitez la sortie formatée. Des diffs cohérents, pas de débats de style.
4. Validez dans le CI. Une étape de lint JSON attrape les virgules finales et les erreurs de syntaxe avant qu’elles n’atteignent la production.

Cela élimine chaque débat de formatage. Le formateur décide, les autres écrivent du code.

Erreurs courantes

• Virgules finales — l’erreur d’analyse la plus fréquente dans le JSON édité à la main.
• Guillemets simples — valides dans les littéraux d’objet JavaScript, invalides en JSON.
• Clés non citées — { name: "Alice" } est du JavaScript, pas du JSON.
• Commentaires — // ceci n'est pas du JSON ni /* ceci non plus */.
• Indentation mélangée — mélanger tabulations et espaces dans le même fichier.

Collez votre JSON dans un validateur avant de déployer. Cela prend une seconde et épargne trente minutes à déboguer une erreur 400 mystérieuse.