Developer

Why Key Order Doesn't Matter in JSON

Dev Nexus5 min read

JSON object keys are unordered by definition, so re-ordering them changes nothing — but array order is meaningful. Here's why, and what it means for comparing JSON.

One of the most common sources of confusion when comparing or debugging JSON is key order. You see { "name": "Ada", "active": true } in one place and { "active": true, "name": "Ada" } in another and wonder whether something changed. It didn't.

In JSON, the keys of an object are unordered. Re-arranging them produces the exact same object. Arrays, on the other hand, are ordered — their position is part of their meaning. Understanding that one distinction explains a lot about why a good JSON compare behaves the way it does, and why a text diff so often lies.

The Problem

The confusion usually shows up in one of two ways.

First, people expect re-ordered keys to count as a difference. They run two documents through a text diff, see every line flagged because the key order changed, and conclude the data is different when it isn't. The diff invented changes that don't exist.

Second, and more dangerously, people assume the reverse for arrays — that item order is as irrelevant as key order. It isn't. Treating ["read", "write"] and ["write", "read"] as equal can hide a real bug, because for many systems the order of a list is meaningful.

So you end up either chasing phantom differences in object keys or missing genuine ones in arrays. Both come from the same misunderstanding about what JSON guarantees.

The Solution

The JSON specification is explicit: an object is an unordered collection of name/value pairs, while an array is an ordered sequence of values. That single rule tells you everything you need:

Object keys have no order. { "a": 1, "b": 2 } and { "b": 2, "a": 1 } are the same object. Re-ordering keys is a no-op.
Array items have a fixed order. [1, 2] and [2, 1] are different arrays, because index [1, 2] and index [2, 1] hold different values.

A structural comparison honours both rules. The JSON Compare tool matches object keys by name and ignores their order, so re-ordered keys never show up as differences — but it compares array items index by index, so a reordered list is correctly reported as changed. It all runs in your browser, so nothing is uploaded. If two documents look different only because their keys are arranged differently, a quick pass through the JSON Formatter will sort or normalise them so they read the same to a human, too.

Step-by-Step Guide

1
Confirm the JSON spec's rule
Remember the definition: a JSON object is an unordered set of name/value pairs; a JSON array is an ordered list of values. Every correct behaviour around key and array order follows directly from this. When in doubt, come back to it.
2
Test key order with a structural compare
Paste { "a": 1, "b": 2 } and { "b": 2, "a": 1 } into JSON Compare. It reports no differences, confirming that key order is irrelevant. A text diff, by contrast, would flag both lines — a good demonstration of why the tools differ.
3
Test array order the same way
Now compare [1, 2] with [2, 1]. This time the tool reports changes at index [1, 2] and index [2, 1], because arrays are ordered. Seeing both results side by side makes the distinction concrete.
4
Normalise when you need a human-readable match
If you want two documents to look identical for a manual review, run each through the JSON Formatter to pretty-print and, where supported, sort keys. The data is already equal; this just makes that obvious to the eye.

Common Mistakes

Treating re-ordered keys as a real change
If your diff flags re-arranged object keys, it's comparing text, not structure. The objects are equal. Switch to a structural compare so key order stops producing false positives — see How to Diff Two JSON Files Online.
Assuming array order is also irrelevant
It isn't. Reordering array items produces a genuinely different array, and many systems (permissions, steps, sequences) depend on that order. Never sort arrays before comparing unless you're certain order is meaningless for your data.
Relying on a serializer to preserve key order
Some libraries preserve insertion order, others don't, and the spec doesn't require it. Don't build logic that depends on keys coming back in a particular order — treat objects as unordered, as JSON defines them.
Using key order to store meaning
If the order of things matters to your application, model it with an array, not by relying on object key order. Object order can be lost at any serialization boundary, so encoding meaning in it is fragile.

Frequently Asked Questions

Does key order matter in JSON?

No. The JSON specification defines an object as an unordered collection of name/value pairs, so `{ "a": 1, "b": 2 }` and `{ "b": 2, "a": 1 }` are the same object. Re-ordering keys changes nothing.

Does array order matter in JSON?

Yes. Arrays are ordered by definition, so `[1, 2]` and `[2, 1]` are different. Each position holds a specific value, and a structural compare reports changes index by index.

Why does my text diff flag re-ordered keys as changes?

Because a text diff compares characters and lines, not structure. It has no idea the objects are equivalent, so it treats a different key arrangement as edited lines. A structural JSON compare ignores key order.

Do JSON parsers preserve key order?

Many do preserve insertion order in practice, but the JSON standard doesn't require it, so you shouldn't depend on it. If order matters to your program, use an array rather than relying on object key order.

How do I make two JSON documents with different key order look the same?

Run each through a formatter that pretty-prints and, ideally, sorts keys. The data is already equal; sorting just makes that visually obvious for a manual review.