JSON has a strict grammar and almost no style rules. Two files can be byte-for-byte different and semantically identical. That freedom is useful for machines and annoying for humans reviewing a diff. A few conventions remove most of the noise.

Pick an indent and keep it

Two spaces is the most common default; four is common in projects that already use four-space JavaScript. Tabs are valid JSON but rare, and mixing tabs with spaces in a file produces diffs that look larger than the actual change. Choose one, configure the formatter, and run it in CI.

{
  "name": "example",
  "nested": {
    "enabled": true
  }
}

Minified JSON is for transport, not for source control. A 200 KB configuration file on one line cannot be reviewed. Keep the readable form in the repository and minify at build time if size matters.

Sort keys when the file is data, not configuration

Sorting keys alphabetically makes diffs stable: adding a key shows one added line instead of a reshuffled block. It also makes it easier to find a key by eye. But some tools care about insertion order, and JSON objects are technically unordered. If order is meaningful, it belongs in an array, not in object keys.

For configuration files that humans edit, preserve the existing order and grouping; reordering the whole file in an unrelated pull request is worse than unsorted keys.

Always end with a newline

POSIX tools expect a trailing newline. Without it, git diff shows \ No newline at end of file, concatenating two files can merge the last and first lines, and some parsers are stricter than others. Most formatters add one; make sure yours does.

Do not rely on duplicate keys

The JSON specification does not define behavior for duplicate object keys. Most parsers keep the last value; some keep the first; some throw. A file with duplicate keys may behave differently in JavaScript, Python and a database importer. If you see them, remove them.

Numbers have limits

JSON numbers are not bounded by the specification, but implementations are. JavaScript parses all numbers as IEEE 754 doubles, so integers above 2^53 lose precision:

JSON.parse('{"id": 9007199254740993}').id // 9007199254740992

IDs, account numbers and large counters should travel as strings when they exceed the safe integer range. This is a data-model decision, not a formatting one, but it surfaces the moment someone round-trips a payload through JavaScript.

Escaping and Unicode

JSON strings can contain any Unicode character. Escaping non-ASCII characters as \uXXXX is valid but makes files harder to read and larger; most modern tooling handles UTF-8 directly. Escape only what the grammar requires: quotes, backslashes and control characters.

Do not hand-escape strings. Use a serializer. Manual escaping produces invalid \x sequences, unescaped newlines and broken surrogate pairs.

Formatting for diffs

A practical workflow:

  1. Format both sides before comparing, so whitespace is not part of the diff.
  2. Sort keys only if the file's order is not meaningful.
  3. Compare line by line for review; use a semantic comparison when key order may differ.
  4. Validate after editing, especially after resolving merge conflicts.

Merge conflicts in JSON are particularly ugly because a missing comma can invalidate the entire file. After resolving one, run the JSON validator before committing.

A checklist

  • Valid JSON, no comments or trailing commas.
  • Consistent indentation, two or four spaces.
  • Trailing newline.
  • No duplicate keys.
  • Large integers encoded as strings.
  • Keys sorted only when order is not semantic.
  • Formatter enforced in CI or a pre-commit hook.

None of this is exotic. The point is to make the file boring: easy to review, hard to break, and identical after two people format it.

The JSON formatter applies indentation and reports syntax errors with a line and column. The sort keys tool is useful when a file genuinely has no meaningful order.