Sort JSON Keys

JSON Key Sorting: Why Sort, and What Sorting Breaks

Sorting is safe — at the semantic level

The JSON specification says an object is an unordered collection of key-value pairs, and the order in which keys appear carries no meaning. So sorting an object's keys alphabetically still yields the same data, and any conforming parser will treat the two as equivalent.

That property makes sorting a safe normalization step. Its three main uses are:

• Cleaner diffs. Once both sides share key order, a text diff flags only the fields that truly changed, instead of lighting up red and green purely from order differences. This is valuable for version-controlling config files and for comparing API responses.
• Reproducible output. In build artifacts, code generation, and snapshot tests, the same input must produce byte-identical output, or CI will keep reporting false differences.
• Stable hashes. JSON is often used to build signatures and cache keys. Different key order produces a different serialized string and therefore a different hash — one object yields two signatures, every cache entry misses, and signature verification fails. Sorting (together with number-format normalization) is the standard remedy; the full procedure is called JSON canonicalization, defined by RFC 8785 (JCS).

What sorting breaks

The spec says order is meaningless, but in reality a great deal depends on order:

• Array order must never be touched. An array is an ordered set, and [1,2,3] is not [3,2,1]. A sort must process only object keys and leave arrays exactly as they are. If a tool also sorts array elements, it silently alters your data.
• Display order. Some systems render forms, table columns, or menu items directly from JSON key order. Sorting turns a carefully arranged interface into alphabetical order.
• Downstream code that relies on insertion order. Some languages' object implementations (JavaScript with string keys, for instance) preserve insertion order, and some business logic exploits that for an implicit sort. Sorting changes that behavior.
• Hand-maintained configuration. The intent of keeping related items together (placing host next to port, for example) is scattered by alphabetical order, and readability actually drops.

The conclusion: sorting suits JSON consumed by machines (signatures, cache keys, snapshots, CI artifacts), not JSON read and maintained by humans — unless you accept the readability cost of alphabetical order.

Details inside the sorting rule

Also note: sorting does not fix duplicate keys. When two same-named keys appear in JSON, sorting brings them together, but the data is still broken (the spec leaves duplicate-key behavior undefined, and most implementations keep the last). A duplicate key should be fixed at the source, not sorted away.

How to use this tool

The tool offers top-level sorting and recursive sorting, with optional ascending or descending order and an option to preserve array order (recommended). On a parse failure it reports the syntax error with its location rather than emitting a silently corrupted result.