Custom Indentation Options in JSON Formatting Tools

Custom indentation does not change what JSON means, but it has a major effect on how quickly people can read, review, and debug it. For most real-world workflows, the useful questions are straightforward: tabs or spaces, how wide each level should be, whether short arrays stay on one line, and whether the tool still outputs strict JSON that every parser accepts.

If you want a safe default, use spaces with 2-space indentation, keep a final newline, and format in strict JSON mode. That combination is compact, readable, and broadly compatible across editors, APIs, and version control.

What the JSON Standard Actually Says

Standard JSON does not require 2 spaces, 4 spaces, tabs, or any other specific formatting style. The JSON specification only treats whitespace as insignificant around structural characters such as commas, colons, braces, and brackets.

• Indentation is presentation, not data: A minified document and a pretty-printed document represent the same JSON values.
• Only a few whitespace characters are valid in JSON: space, horizontal tab, line feed, and carriage return.
• Comments and trailing commas are not part of standard JSON: if a tool accepts them, it is using a relaxed mode such as JSONC or JSON5-style behavior, not strict JSON.

{"user":{"name":"John","profile":{"age":30,"roles":["admin","editor"]},"settings":{"notifications":true,"theme":"dark"}}}

{
  "user": {
    "name": "John",
    "profile": {
      "age": 30,
      "roles": [
        "admin",
        "editor"
      ]
    },
    "settings": {
      "notifications": true,
      "theme": "dark"
    }
  }
}

Indentation Options That Actually Matter

1. Tabs or spaces

This is the first setting most JSON formatting tools expose, and it affects more than visual style.

• Spaces: Predictable in browsers, review tools, pasted snippets, documentation, and issue trackers.
• Tabs: Smaller file size and adjustable visual width, but the rendered width depends on the viewer's editor settings.

For shared JSON files, spaces are usually safer. Tabs are valid JSON whitespace, but they often create uneven alignment in Git diffs, web previews, or editors with different tab-width settings.

2. Indent width

The next decision is how much visual separation you want at each nesting level.

• 2 spaces: Usually the best default for API payloads, config files, and mobile-sized screens.
• 4 spaces: Easier to scan in deeply nested data, but it wraps earlier and creates longer diffs.
• Tabs: Useful when each developer wants a different visual width, as long as the team also agrees on a display convention.

3. Compact versus multiline containers

Better formatters also decide when arrays and objects should stay on one line and when they should expand.

• Compact small arrays: Good for short lists like feature flags or enum-like values.
• Multiline expansion: Better for nested objects, long strings, and reviewability.
• Threshold-based wrapping: Some tools switch layout based on item count or line length.

{
  "colors": [
    "red",
    "green",
    "blue"
  ]
}

{
  "colors": ["red", "green", "blue"]
}

4. End-of-line details

Indentation settings are often bundled with line-ending and newline rules because they affect diffs just as much as spaces and tabs do.

• Final newline: Keeping one at the end of the file makes diffs cleaner in many tools.
• Line endings: Normalize to LF unless your environment requires otherwise.
• Whitespace around separators: Most formatters standardize a single space after colons and commas in pretty output.

These settings do not change the parsed data, but they do reduce noisy version-control churn when multiple people edit the same JSON files.

How Real Tools Behave Today

JavaScript-based formatters and scripts

A lot of JSON formatting on the web still follows JavaScript behavior similar to JSON.stringify(value, replacer, space).

• Numeric indent values are capped: JavaScript limits them to 10 spaces per nesting level.
• Custom indent strings are also capped: only the first 10 characters are used.
• Tabs are allowed: passing "\t" produces tab-indented output.

JSON.stringify(data, null, 2);    // 2 spaces
JSON.stringify(data, null, 4);    // 4 spaces
JSON.stringify(data, null, "\t"); // tabs

JSON.stringify(data, null, 12);      // behaves like 10 spaces
JSON.stringify(data, null, "............"); // first 10 characters only

If a browser-based formatter refuses a very wide indent or shortens a custom indent token, it may be inheriting this JavaScript limit rather than ignoring your setting.

Editors and IDEs

Editors can make JSON formatting feel inconsistent because they may support both strict JSON and relaxed variants.

• Strict JSON mode: Best for files that will be parsed by APIs, CLIs, CI jobs, or other machines.
• Relaxed modes such as JSONC: Useful for editor settings files, but comments and trailing commas can break strict parsers elsewhere.
• Editor defaults still matter: tab width and indentation detection can change how the same file looks from one environment to another.

Team-wide settings with .editorconfig

When several people or tools touch the same JSON files, encode the rule once instead of relying on personal editor defaults.

[*.json]
indent_style = space
indent_size = 2
insert_final_newline = true

If your team prefers tabs, switch to indent_style = tab and agree separately on display width with tab_width or editor settings. The important part is that everyone is reading from the same source of truth.

Choosing the Right Indentation for Your Use Case

• API examples and documentation: Use spaces, usually 2 spaces, because the output will look consistent anywhere it is pasted.
• Human-edited config files: Use 2 spaces for compactness unless the structure is deeply nested and your team strongly prefers 4.
• Large files under active review: Favor the style that produces the smallest clean diffs, which is usually spaces plus a stable formatter.
• Personal local inspection: Tabs can work well if you control the editor and want adjustable visual width.

Troubleshooting Unexpected Formatter Output

• Your 12-space indent keeps shrinking: The formatter may be using JavaScript's indentation limit of 10 characters.
• Tabs look different on another machine: That is usually an editor tab-width issue, not a JSON parsing issue.
• The tool keeps some arrays on one line: Look for a wrap threshold, print width, or compact array setting. Not every formatter exposes that separately.
• An API rejects the formatted file: Revalidate it in strict JSON mode and remove comments, trailing commas, and non-JSON syntax such as single-quoted keys.

Conclusion

Custom indentation options are useful when they solve concrete workflow problems, not when they add endless style knobs. The most valuable controls are still the simplest ones: tabs versus spaces, indent width, compact versus multiline layout, and strict output that stays valid JSON.

If you are choosing defaults for a formatter today, spaces with 2-space indentation remains the safest option for compatibility and readability. If you choose something else, document it and enforce it consistently so your tooling stops fighting your team.