JSON Sort Keys

Object key order is not semantic

The JSON specification treats objects as unordered, so two documents with the same pairs in different order are equivalent. Most parsers preserve insertion order in practice, which means a serialiser that emits keys in a different order produces a file that diffs as entirely changed while being identical in meaning.

This is why sorting matters in version control

An API response or a config file regenerated by a tool with non-deterministic key order creates enormous diffs with no real changes, burying the one line that actually differs. Sorting keys canonically before committing makes diffs reflect substance. The same applies to comparing two environments' configuration, where unsorted output makes a genuine difference impossible to spot.

Arrays must not be reordered

Array order is semantic in JSON. A sorter must recurse into arrays to sort the objects inside them while leaving the array sequence untouched. A tool that sorts array elements corrupts the data, and it is a real failure mode worth checking before trusting output.

Canonical forms go further

Where JSON is signed or hashed, key order alone is not enough — whitespace, number formatting, and Unicode escaping all have to be fixed too. JCS, defined in RFC 8785, specifies a full canonicalisation for exactly this purpose. Sorting keys is a useful convenience; it is not a canonical form.

Duplicate keys are undefined behaviour

The specification does not forbid them, and parsers differ on whether the first or last wins. Sorting surfaces duplicates by placing them adjacent, which makes an otherwise invisible ambiguity obvious.