Developer tools · JSON formatter & validator
Why a consistent JSON indent keeps your git diffs readable
· Why it matters
json developer-workflow validation
When two tools disagree about indentation, every JSON file in a repository shows up as changed. This post explains why indent consistency matters for review, how to pick one, and how to reformat safely.
Four hundred lines changed, one value edited
Four hundred lines changed, one value edited — the pull request nobody can review because an editor reformatted the file. A line-based diff treats indentation changes as replacements, so the intended version bump disappears among mechanically altered lines. Reviewers either spend time filtering noise or approve without confidently checking the semantic edit.
ToolAcre can match two, four or eight spaces or a tab, and can sort keys when deliberately selected. It does not preserve original line endings because JSON.stringify emits new text. Teams should separate a repository-wide normalization from a semantic edit if they want the review diff to remain intelligible. Formatting policy should be chosen before broad rewrites.
Whitespace is insignificant to JSON and very significant to diff
Whitespace is insignificant to JSON and very significant to diff — why a change of indent rewrites every line. Parsers ignore spaces, tabs and line breaks outside strings, but version-control comparison begins with text lines. Changing two leading spaces to four alters nearly every nested line even though the resulting data structure is identical.
That noise has consequences beyond aesthetics. Blame history moves to the normalization commit, merge conflicts increase on branches using the previous layout, and code review loses its normal signal-to-noise ratio. Stable formatting lets a one-value edit remain a one-line change. Apply normalization once, communicate it and avoid mixing it with functional configuration changes. Repository-wide consistency also lets reviewers recognize unexpected formatter output immediately and keeps automated change summaries focused on actual configuration behavior changes.
Two spaces, four spaces or tabs
Two spaces, four spaces or tabs — what common ecosystems default to, and why the choice matters less than sticking to it. Two spaces keep deeply nested documents narrower; four create stronger visual separation; tabs allow display width preferences but can interact poorly with alignment and tools that silently convert them.
Choose the convention already dominant in the repository and encode it in Prettier, EditorConfig or the generating tool rather than relying on memory. Ensure contributors and CI use compatible versions. JSON grammar accepts each option, so arguments about universal correctness miss the operational point: deterministic output prevents editors, generators and formatters from taking turns rewriting the same file. Pinning formatter versions avoids policy drift after upgrades.
Line endings and trailing newlines
Line endings and trailing newlines — CRLF versus LF and the missing final newline as the other sources of whole-file diffs. A checkout configured for CRLF can appear to replace every line when a formatter emits LF. The parsed JSON is unchanged, but Git and review interfaces may display a repository-wide textual rewrite.
Set line-ending policy deliberately through repository attributes and formatter configuration, then verify it on the platforms contributors use. Preserve the customary final newline so command-line tools and diffs do not report the last line awkwardly. Because parse-and-reserialize tools generate fresh text, compare the resulting byte-level conventions before applying them to many files. A hexadecimal check can distinguish line-ending churn from value changes.
Worked example: normalising a repository's JSON
Worked example: normalising a repository's JSON — inventory strict JSON files, select the existing two-space convention and reformat them in a dedicated change. Exclude generated artifacts whose producers own serialization and JSON-like dialects that the strict formatter cannot parse. Run tests before and after to verify consumers still read equivalent values.
Merge or rebase active feature branches around the normalization window to reduce conflicts, then enforce the chosen formatter in CI. The normalization review should contain no key sorting or value edits, making structural equivalence easier to establish. Subsequent pull requests can show a dependency version update or flag change on the precise line where it occurred.
Reviewing a JSON change well
Reviewing a JSON change well — formatting both versions identically before comparing, so only the semantic change stands out. Check whether arrays changed order, whether a number became a string and whether a key disappeared rather than moving. Quotes and literal types carry meaning that indentation alone cannot evaluate.
Avoid sorting keys unless the repository explicitly treats order as irrelevant and expects canonical sorting. Although object member order often lacks application meaning, reordering expands diffs and can affect tools that preserve insertion order. For security-sensitive policies or manifests, pair the textual review with schema validation and a consumer-specific check rather than approving solely because the formatted diff is small.
What this does not cover
What this does not cover — key ordering and semantic diffing, which need tools that understand structure rather than lines. Two documents can serialize differently while producing equivalent objects, and two identical-looking values can have different consequences under an application schema. Formatting standardizes presentation but does not define semantic equivalence.
It also does not guarantee byte preservation. Reserialization can normalize escapes and number spellings, change line endings and round unsafe JavaScript integers. Generated files may require an exact producer version, and signed documents must not be rewritten casually. Establish whether the artifact is source, generated output or canonical signed data before applying repository-wide formatting.
Takeaway: one indent, enforced early
Takeaway: one indent, enforced early — use the formatter's indent setting to match the project rather than impose a personal preference. Align line endings and final-newline policy at the same time, then automate those choices so every editor and CI run produces stable text. Consistency protects review quality more than any particular width.
If normalization is necessary, isolate it from semantic work and announce it to active branches. Inspect reserialized output for large integers, escape changes and unwanted key sorting before committing it. Once the baseline is stable, ordinary JSON changes stay narrow, blame remains useful and reviewers can focus on values and structure instead of reconstructing intent from formatting noise.