JSON Sort Keys

RFC 8259 is explicit that a JSON object is an unordered collection of name/value pairs. Two documents whose keys appear in different orders are the same document as far as the specification is concerned, and any correct consumer must treat them identically.

In practice, though, every mainstream parser preserves insertion order, and `JSON.stringify` writes keys back in that order. So the ordering survives round trips even though nothing depends on it - which means an unrelated change upstream, a different library version, or a map iteration order can reshuffle a file and produce a diff with dozens of changed lines and zero changed data.

Sorting keys removes that noise permanently. Once every document is written in the same canonical order, a diff shows only what actually changed. This is the entire reason the operation exists.

Sorting is recursive: every object at every depth is reordered, not just the top level. That is what makes the result canonical - a partially sorted document would still diff noisily whenever a nested object shifted.

Array order is never touched, and this distinction matters. An object is unordered by definition, so reordering its keys is information-preserving. An array is ordered by definition, so reordering its elements would change the data. A tool that sorted arrays too would be silently corrupting documents, which is why this one does not.

The comparison itself is lexicographic on the UTF-16 code units of each key, matching JavaScript's default string sort. That is stable and predictable, but it is not the same as human alphabetical order: uppercase letters sort before all lowercase letters, so `Zebra` comes before `apple`. Digits sort before letters, and `item10` sorts before `item2` because the comparison is character by character rather than numeric.

Sorted keys are one part of what people mean by canonical JSON - a single, deterministic byte representation for a given value. The other parts are consistent whitespace, consistent number formatting, and consistent string escaping. Combine sorting with minifying and you have something close enough to canonical form for most practical purposes.

This matters when you hash or sign a payload. If two systems serialise the same data with different key orders, they produce different bytes and therefore different hashes, and a signature check fails even though nothing is wrong. Canonicalising before hashing is the standard fix. If you need this for cryptographic verification rather than for diffing, look at RFC 8785 (JSON Canonicalization Scheme), which pins down the number and string rules that a sort alone leaves open.