Sort JSON

Sorting object keys alphabetically, recursively through every nested object. Array order is never touched, because array order is meaningful and object key order is not.

The reason to do it is diffs. Two files with the same content in a different key order produce a diff full of noise. Sort both and the diff shows only what actually changed.

When sorting is the right move

Before committing a generated file

Lock files, exported configuration and anything a tool writes. If the generator does not guarantee an order, sorting makes the file stable across runs and machines.

Before comparing two documents

Sorting both first turns a text diff into something readable. Our structural diff ignores key order anyway, so this is mainly for tools that do not.

For a canonical form

Hashing or signing a document needs a deterministic serialisation. Sorting keys is one part of that; RFC 8785, JSON Canonicalization Scheme, specifies the rest including number formatting and string escaping.

When sorting is the wrong move

A hand-maintained configuration file where the order carries meaning for the reader: the important settings at the top, related ones grouped together. Sorting it alphabetically is technically harmless and practically annoying.

Anything where a consumer depends on key order. Nothing should, but some hand-rolled parsers do, and finding out in production is expensive.

How the comparison works

Case-sensitive by default, which sorts uppercase before lowercase because that is their code point order. Turn on case-insensitive comparison to get the ordering people usually expect from a list of names.

Note that this is a code point sort, not a locale-aware one. It is deterministic everywhere, which is what a canonical form needs; a locale-aware sort would produce different files on different machines.

How to do this in code

Sorting keys in 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

Does sorting change my data?

Not semantically. JSON objects are unordered by specification, so a sorted document holds the same value. It does change the bytes, which is the point.

Why are array elements not sorted?

Because array order is part of the data. Sorting [3,1,2] into [1,2,3] would be changing the document, not reformatting it.

Is this the same as canonical JSON?

It is one part of it. RFC 8785, the JSON Canonicalization Scheme, also specifies number formatting, string escaping and Unicode normalisation, all of which matter if you are hashing or signing the result.