Key Reordering in JSON Diff

The JSON specification (RFC 8259) states that objects are unordered collections of key-value pairs. This means {"a":1,"b":2} and {"b":2,"a":1} are semantically identical. However, in practice, key order can vary between serializers, languages, and versions, leading to questions about how diff tools should handle it.

Semantic vs. textual comparison:

A textual diff (comparing JSON as raw strings) will report reordered keys as changes because the character sequences differ. A semantic diff (parsing both documents into data structures first) will correctly identify that reordered keys produce no meaningful difference.

// Document A
{
  "name": "Widget",
  "price": 29.99,
  "category": "tools",
  "inStock": true
}

// Document B
{
  "category": "tools",
  "inStock": true,
  "name": "Widget",
  "price": 29.99
}

A semantic JSON diff reports zero differences because all keys and values are identical. A line-based text diff would report every line as changed.

Why key order varies:

• Language differences: Python dictionaries (3.7+) preserve insertion order. Go maps iterate in random order. Java HashMap has no guaranteed order. When different services serialize JSON, key order may differ.
• Serializer settings: Some JSON libraries offer a "sort keys" option. If one version of a document was serialized with sorted keys and another was not, every key appears to have moved.
• Database round-trips: Storing JSON in a database and retrieving it may change key order depending on the storage engine.

Best practices:

• Always use a semantic (parsed) diff tool rather than a textual diff for JSON comparison.
• If you must use text-based comparison (e.g., in git), sort keys before committing. JSON.stringify(data, null, 2) in JavaScript preserves insertion order; use a sorted replacer or json.dumps(data, sort_keys=True) in Python.
• Configure your diff tool to ignore key order if it offers that option.