How to format JSON

Formatting is a parse, not a text transform

A correct formatter parses the document into values and prints those values again. It does not insert newlines into a string with a regular expression. That distinction matters for two reasons: anything the formatter produces is guaranteed to be valid, and a document that cannot be parsed cannot be formatted at all — which is why a formatter reporting an error is doing its job.

{"order":{"id":9912,"items":[{"sku":"A-1","qty":2},{"sku":"B-7","qty":1}],"paid":true}}

{
  "order": {
    "id": 9912,
    "items": [
      { "sku": "A-1", "qty": 2 },
      { "sku": "B-7", "qty": 1 }
    ],
    "paid": true
  }
}

Which indentation

The width has no effect on meaning. Pick the one that matches the repository the file lives in, and be consistent, because a re-indent shows up as a whole-file diff.

• Two spaces — the default in most JavaScript, TypeScript and web tooling. Deep documents stay on screen.
• Four spaces — common in Python, Java and .NET codebases. Easier to follow at a glance, wider at depth.
• Tab — respects each reader’s editor setting. Worth using when the file is committed and read by a mixed team.

When to sort keys

Sorting object keys alphabetically, recursively, makes two documents comparable. If you are diffing an API response captured today against one captured last month, sorting both first removes every difference that is only key order — which is not a difference at all, because JSON does not define object key order.

Do not sort a file you are going to commit unless the whole team does. A one-off sort turns into an enormous diff that hides the actual change.

Large integers change unless you ask them not to

This is the failure that costs the most time, because nothing reports it. An id such as 9007199254740993 goes through a JavaScript-based formatter and comes out as 9007199254740992 — a different number, silently.

Every formatter built on JSON.parse has this behaviour, including browser dev tools. Turn on Big Number mode when a document contains ids, account numbers or Snowflake-style keys: it keeps the original digits exactly and tells you how many it protected.

input   {"id": 9007199254740993}
output  {"id": 9007199254740992}

Formatting and file size

Indentation typically adds 15–30% to a document’s size. That is irrelevant on disk and irrelevant over a gzipped connection — repeated whitespace compresses to almost nothing. Format for reading, minify for embedding in a URL or a fixed-size field, and do not minify for transport on the assumption that it helps.