🛠️Developer

JSON Formatting: A Developer's Real-World Guide

Not the beginner tutorial. How JSON formatting decisions affect your team, your APIs, and your debugging workflow — with specific recommendations.

8 min readSeptember 5, 2025By FreeToolKit TeamFree to read

JSON formatting arguments in code reviews waste more time than they're worth. Tabs vs spaces, camelCase vs snake_case, null vs undefined — these shouldn't be debates. Here's what actually matters and what you can safely stop arguing about.

The Basics You Should Have Consistent Across Your API

Key naming convention is the one that bites hardest when it's inconsistent. Pick camelCase or snake_case for your keys and enforce it everywhere. userId vs user_id might look minor, but when a mobile developer is parsing your response and finds both, they write fragile code that breaks in strange ways.

Key naming: camelCase for JS/TS APIs, snake_case for Python APIs. Pick one.
Dates: Always ISO 8601. '2025-09-05T14:30:00Z' not '09/05/2025' or 'September 5, 2025'.
Nulls vs missing keys: Be consistent. Either always include null fields or always omit them. Don't do both.
Booleans: Never use 0/1 or 'yes'/'no' in place of true/false. Use actual booleans.
Numbers: Don't wrap numbers in quotes. '42' is wrong; 42 is right.

When to Minify vs When to Pretty-Print

In production APIs: minify. Whitespace adds bytes, bytes add latency, latency hurts users. A 2KB JSON response becomes 1.6KB minified — not huge, but it adds up at scale and gzip will help further.

For config files, storage, and anything humans might read: pretty-print. There's no performance argument for compressing a config file that gets read once at startup. Readability wins.

Format JSON Instantly →

The Underrated One: Consistent Error Shapes

What breaks API integrations more than formatting is inconsistent error responses. When your success response has {data: {...}} and your error response has {error: 'message'} and sometimes it's {errors: [...]} — every client has to handle three different shapes. Pick one error format and use it everywhere. The RFC 7807 'Problem Details' standard is worth looking at.

Tools to Enforce JSON Style

ESLint with JSON plugins — enforces key naming, flag issues at lint time
Prettier — auto-formats JSON files consistently across a codebase
Our online JSON formatter — good for quick validation and formatting one-offs
jq — command-line JSON processor, great for scripts and large files
Spectral — API style linting, goes beyond JSON formatting to API design rules

The Argument That's Actually Worth Having

Pagination format. There's no standard and every team invents theirs. Before bikeshedding about indentation, decide whether your list responses use {data: [], total: 100, page: 1} or {items: [], nextCursor: 'abc'} or {results: [], links: {next: '...'}}. This decision is much harder to change later than two spaces vs four.

Frequently Asked Questions

Should I use 2-space or 4-space indentation for JSON?+

Two spaces is more compact and dominates in JavaScript-heavy codebases (Node.js, Next.js, React). Four spaces is more readable for very deeply nested structures and is common in Java/Python ecosystems. The honest answer: it doesn't matter much as long as your team picks one and enforces it with a linter. Google's style guide says 2 spaces. Airbnb says 2 spaces. Go with 2 unless you have a specific reason.

Should JSON keys use camelCase or snake_case?+

Use camelCase (firstName) for JavaScript/TypeScript APIs — it matches how you'll consume the data. Use snake_case (first_name) for Python backends or when following existing API conventions. Never mix them in the same API. The worst outcome is an API that sometimes returns userId and sometimes user_id. Pick one and document it.

Should I include trailing commas in JSON?+

Standard JSON does not allow trailing commas. If you're working with JSON5 or JSONC (JSON with Comments) you can add them, but pure JSON files will fail to parse with a trailing comma. Most linters will catch this. Stick to standard JSON for anything that crosses API boundaries.

How do I format large JSON files efficiently?+

For files under 10MB, our online JSON formatter handles it instantly in-browser. For larger files, command-line tools are faster: 'cat large.json | python3 -m json.tool > formatted.json' or 'jq . large.json > formatted.json' on Mac/Linux. The browser-based approach is convenient for quick checks; CLI tools are better for automation.

🔧 Free Tools Used in This Guide

Json Formatter Base64 Encoder Regex Tester

FreeToolKit Team

We build free browser-based tools and write practical guides that skip the fluff.

Tags:

jsondeveloperapiformatting

Continue Reading

🔤

Base64 Encoding Explained (With Actual Examples)

6 min read

🔍

Regex for People Who Keep Putting It Off

9 min read