docs / 6 min read
Best JSON Formatting Practices
Readable JSON improves debugging, reviews, documentation, and test maintenance. Formatting is especially important when sharing payload examples, documenting API behavior, or comparing expected and actual responses.
Use consistent indentation
Two-space indentation is common for JSON examples because it balances readability and compactness. Consistent indentation makes nested objects, arrays, and primitive values easier to scan.
Avoid unnecessary escaping
Keep string values readable where possible. Escaped payloads are harder to compare and more likely to hide issues, especially when JSON is copied from logs or embedded inside another string.
Validate before sharing
Always parse JSON before using it in tests or documentation. A missing comma, quote, or bracket can waste debugging time and make a bug report harder to reproduce.
Keep examples focused
A good JSON example should include the fields needed to explain the scenario. Remove unrelated metadata, request ids, and secrets before sharing a payload in documentation or issue trackers.
QA example: Clean a raw API log before creating a bug report
A tester copies a minified API response from browser devtools. After beautifying the JSON, it becomes clear that error.code is correct but error.details[0].message is missing a user-readable explanation.
- Expected payload focus
- The error response should include a code, message, and detailed validation message.
- Actual issue found
- The nested details message is empty, making the frontend error state unhelpful.
Key paths to validate
- $.error.code
- $.error.message
- $.error.details[0].message
Automation assertion example
expect(response.error.code).toBe('INVALID_ADDRESS');
expect(response.error.details[0].message).toEqual(expect.any(String));Practical checklist
- Beautify minified JSON before comparing or sharing it.
- Remove tokens, secrets, and personally identifiable data from examples.
- Keep the payload focused on the failing scenario.
- Validate syntax before adding JSON to a test fixture or documentation page.
Developer and QA tips
- Use consistent formatting in pull requests so reviewers can focus on meaning.
- For large payloads, use tree view instead of scrolling through a long formatted document.
- For copied logs, check whether the JSON is double-encoded before comparing it.
How JSON TreeDiff can help
Use the JSON comparison tool to review payload differences, switch to the tree viewer to inspect nested structures, and copy generated key paths into your API validation workflow. The tool runs in your browser and does not upload pasted JSON to a server.
Open the JSON tool