JSON Formatting Tips for Developers

·4 min read

If you've spent any time writing APIs, configuring tools, or debugging webhooks, you've stared at a wall of JSON. Minified JSON is barely readable. A misplaced comma can break an entire configuration. And nested objects three or four levels deep turn into a headache fast.

Good JSON formatting habits save debugging time, reduce errors, and make your code reviews less painful. Here's what actually matters in practice.

Why Formatting Isn't Just Cosmetic

Take this chunk of minified JSON:

`{"users":[{"id":1,"name":"Alice","roles":["admin","editor"],"settings":{"theme":"dark","notifications":{"email":true,"push":false}}},{"id":2,"name":"Bob","roles":["viewer"],"settings":{"theme":"light","notifications":{"email":false,"push":true}}}]}`

Now the same data, formatted:

{
  "users": [
    {
      "id": 1,
      "name": "Alice",
      "roles": ["admin", "editor"],
      "settings": {
        "theme": "dark",
        "notifications": {
          "email": true,
          "push": false
        }
      }
    }
  ]
}

The second version lets you instantly see the structure, spot missing fields, and compare objects. In a code review, that's the difference between a 30-second glance and a 10-minute squint.

Minified JSON is for machines. Formatted JSON is for humans. Use minified for production API responses (saves bandwidth). Use formatted everywhere else.

The Trailing Comma Problem

JSON does not allow trailing commas. This is valid JavaScript but invalid JSON:

{
  "name": "Alice",
  "age": 30,    ← trailing comma = parse error
}

This single comma has caused countless hours of debugging. It's the most common JSON syntax error, and it's invisible in large files.

  • Use a JSON validator before deploying config files
  • Most code editors highlight JSON syntax errors (VS Code does this automatically for `.json` files)
  • Lint your JSON in CI/CD pipelines — a failed lint is better than a failed deploy

Prevention tip: When adding items to JSON arrays or objects, add the comma *before* the new item rather than after the previous one. Some developers put commas at the start of lines for exactly this reason (though that's a style debate for another day).

Consistent Indentation: Pick One and Stick With It

  • **2 spaces** — more compact, popular in JavaScript/TypeScript ecosystems
  • **4 spaces** — easier to scan nested structures, common in Python-adjacent projects

Tabs are technically valid but uncommon in JSON and can cause inconsistent rendering across tools.

What matters most: consistency within a project. If your API responses use 2-space indentation but your config files use 4-space, anyone reading both will be confused.

Add a `.editorconfig` file to your project: ``` [*.json] indent_style = space indent_size = 2 insert_final_newline = true ```

This ensures everyone on the team formats JSON the same way, regardless of their editor settings.

Key Naming Conventions

JSON keys are just strings, so technically anything goes. But consistent naming makes your data predictable.

camelCase — `firstName`, `emailAddress`, `createdAt` Most common in JavaScript/TypeScript. Matches the language's native conventions.

snake_case — `first_name`, `email_address`, `created_at` Common in Python, Ruby, and their ecosystem's APIs. PostgreSQL column names typically use this.

kebab-case — `first-name`, `email-address` Rare in JSON because it requires quoting in most languages. Avoid unless you have a specific reason.

PascalCase — `FirstName`, `EmailAddress` Used in some .NET APIs and C# conventions.

The rule: Match your API's naming convention to the primary consuming language. If your frontend is JavaScript and your API returns snake_case, you'll be converting between conventions everywhere. That's wasted effort.

Structuring Nested Data

Deeply nested JSON is hard to work with. If your data is nested more than 3–4 levels deep, consider flattening.

Hard to work with: ```json { "company": { "departments": { "engineering": { "teams": { "frontend": { "lead": "Alice" } } } } } } ```

Accessing the lead requires: `data.company.departments.engineering.teams.frontend.lead` — any null in that chain and your code crashes.

Better approach — flatten with references: ```json { "teams": [ { "id": "frontend", "department": "engineering", "lead": "Alice" } ] } ```

Access: `data.teams[0].lead` — simpler, safer, easier to iterate.

  • 1–2 levels deep: fine, use freely
  • 3 levels: acceptable if the structure genuinely requires it
  • 4+ levels: flatten or restructure

Common JSON Mistakes and Fixes

1. Using single quotes instead of double quotes ``` {'name': 'Alice'} ← Invalid JSON {"name": "Alice"} ← Valid ``` JSON requires double quotes for both keys and string values. No exceptions.

2. Unquoted keys ``` {name: "Alice"} ← Invalid JSON (valid JavaScript, though) {"name": "Alice"} ← Valid ```

  • **JSON5** — extends JSON with comments, trailing commas, and more
  • **JSONC** — JSON with Comments, used by VS Code settings files
  • **YAML** — a JSON superset that supports comments natively
  • A `"_comment"` key as a workaround (hacky but functional)

4. Numbers with leading zeros ``` {"code": 007} ← Invalid JSON {"code": 7} ← Valid (or use "007" as a string) ```

5. Using `undefined` or `NaN` JSON supports `null`, `true`, `false`, numbers, strings, arrays, and objects. That's it. No `undefined`, no `NaN`, no `Infinity`, no functions.

Debugging Malformed JSON

When your JSON won't parse and you can't spot the error, try this systematic approach:

1. Paste it into a JSON validator — tools like our JSON Formatter highlight exactly where the parse error occurs, with line numbers.

2. Binary search for the error — delete the second half of the file. Does it parse? If yes, the error is in the deleted half. Repeat until you narrow it down.

3. Check for invisible characters — copy-pasting from Word, PDFs, or Slack can introduce smart quotes ("" instead of ""), en-dashes, or zero-width spaces. These are invisible but fatal to JSON parsers.

4. Validate encoding — JSON must be UTF-8 (or UTF-16/32 with a BOM, though UTF-8 is standard). A file saved as Latin-1 with accented characters will break.

5. Look for escaped characters — Strings containing backslashes, quotes, or newlines must be properly escaped: `\\`, `\"`, `\n`.

JSON in API Design

If you're designing an API that produces JSON, a few conventions improve developer experience:

  • **Consistent response structure** — always return `{"data": ..., "error": null}` or similar. Don't change the shape between success and error states.
  • **ISO 8601 for dates** — `"2026-02-06T14:30:00Z"`, not `"Feb 6, 2026"` or Unix timestamps.
  • **Pagination with cursors** — `{"data": [...], "next_cursor": "abc123"}` scales better than offset/limit for large datasets.
  • **Envelope pattern** — wrapping your response in a standard envelope makes it easier to add metadata later without breaking existing clients.

Useful Tools for Working with JSON

  • **jq** — command-line JSON processor. Indispensable for parsing API responses in scripts. `curl api.example.com | jq '.users[0].name'`
  • **JSON Crack** — visualizes JSON as an interactive graph. Great for understanding complex nested structures.
  • **VS Code** — built-in JSON formatting (Shift+Alt+F), syntax highlighting, and validation.
  • **Our JSON Formatter** — paste, format, validate, and copy. No install, no sign-up.

Format and validate your JSON instantly with our free JSON Formatter — it catches syntax errors and prettifies your data in one click.

Related Tools

json formatter
← Back to Blog