Trier du JSON

Trie les clés des objets par ordre alphabétique, récursivement à travers chaque objet imbriqué. L’ordre des tableaux n’est jamais touché, parce que l’ordre d’un tableau a un sens et celui des clés d’un objet non.

La raison de le faire, ce sont les diffs. Deux fichiers au contenu identique dans un ordre de clés différent produisent un diff plein de bruit. Triez les deux et le diff ne montre plus que ce qui a réellement changé.

Quand trier est le bon geste

Avant de committer un fichier généré

Fichiers de verrouillage, configuration exportée, et tout ce qu’un outil écrit. Si le générateur ne garantit aucun ordre, trier rend le fichier stable d’une exécution et d’une machine à l’autre.

Avant de comparer deux documents

Trier les deux d’abord transforme un diff textuel en quelque chose de lisible. Notre diff structurel ignore de toute façon l’ordre des clés : c’est donc surtout utile pour les outils qui ne l’ignorent pas.

Pour obtenir une forme canonique

Hacher ou signer un document exige une sérialisation déterministe. Trier les clés en est une partie ; la RFC 8785, le JSON Canonicalization Scheme, spécifie le reste, y compris le formatage des nombres et l’échappement des chaînes.

Quand trier est une erreur

Un fichier de configuration maintenu à la main où l’ordre porte du sens pour le lecteur : les réglages importants en haut, les réglages liés regroupés. Le trier alphabétiquement est techniquement inoffensif et pratiquement pénible.

Tout ce dont un consommateur dépend en matière d’ordre des clés. Rien ne devrait en dépendre, mais certains analyseurs faits maison le font, et le découvrir en production coûte cher.

Comment fonctionne la comparaison

Sensible à la casse par défaut, ce qui place les majuscules avant les minuscules parce que c’est leur ordre de points de code. Activez la comparaison insensible à la casse pour obtenir l’ordre que l’on attend habituellement d’une liste de noms.

Notez qu’il s’agit d’un tri par point de code, pas d’un tri sensible à la locale. Il est déterministe partout, ce dont une forme canonique a besoin ; un tri sensible à la locale produirait des fichiers différents sur des machines différentes.

How to do this in code

Trier les clés en code.

jq -S . input.json          # sort keys, recursively
jq -S -c . input.json       # sorted and compact

import json

# sort_keys applies recursively
out = json.dumps(json.loads(text), sort_keys=True, indent=2)

// The replacer only receives keys, so sorting needs a walk.
function sortDeep(value) {
  if (Array.isArray(value)) return value.map(sortDeep);
  if (value && typeof value === 'object') {
    return Object.fromEntries(
      Object.keys(value).sort().map((k) => [k, sortDeep(value[k])]),
    );
  }
  return value;
}

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

// encoding/json sorts map keys automatically when marshalling
// a map. Struct fields keep their declaration order.
var v map[string]any
json.Unmarshal(data, &v)
out, _ := json.MarshalIndent(v, "", "  ")   // keys sorted

Questions fréquentes

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

Pas sémantiquement. Les objets JSON ne sont pas ordonnés d’après la spécification, un document trié contient donc la même valeur. Il modifie les octets, et c’est bien le but.

Pourquoi les éléments des tableaux ne sont-ils pas triés ?

Parce que l’ordre d’un tableau fait partie des données. Transformer [3,1,2] en [1,2,3] reviendrait à modifier le document, pas à le remettre en forme.

Est-ce la même chose que du JSON canonique ?

C’en est une partie. La RFC 8785, le JSON Canonicalization Scheme, spécifie aussi le formatage des nombres, l’échappement des chaînes et la normalisation Unicode, ce qui compte dès que vous hachez ou signez le résultat.