How to Format JSON: A Practical Developer Guide

JSON formatting (also called JSON pretty-printing) is the process of adding whitespace, indentation, and line breaks to JSON data to make it human-readable. Crucially, the actual data structure and values do not change — only the visual presentation.

When I was a junior developer, I once spent 45 minutes trying to debug a minified API response before I realized I just needed to format it. That lesson stuck: always format JSON before trying to understand it.

Here's a concrete example. This minified JSON is technically valid but almost impossible to scan:

{"status":"success","data":{"id":123,"items":[{"name":"Widget","price":29.99,"inStock":true,"variants":["small","medium","large"},{"name":"Gadget","price":49.99,"inStock":false,"variants":["red","blue"]}]}}

When formatted with proper indentation (2 spaces is the de facto standard), the same data becomes instantly understandable:

{
  "status": "success",
  "data": {
    "id": 123,
    "items": [
      {
        "name": "Widget",
        "price": 29.99,
        "inStock": true,
        "variants": ["small", "medium", "large"]
      },
      {
        "name": "Gadget",
        "price": 49.99,
        "inStock": false,
        "variants": ["red", "blue"]
      }
    ]
  }
}

The difference is night and day. You can immediately see we have two items, check which are in stock, and understand the nested structure at a glance. All programming languages parse both versions identically because JSON parsers ignore all whitespace outside of strings. Formatting is purely for humans — but that's you, and it matters a lot.

The JSON spec doesn't mandate any particular indentation style, but 2 spaces is the most common convention you'll encounter in the wild.

You should format JSON whenever a human needs to read, understand, or debug JSON data. Here are the situations I encounter most frequently in daily development work:

**Debugging API responses in browser dev tools**: When you inspect network tab and see that JSON come back, the browser usually has a 'Pretty Print' button — use it. I can't tell you how many times I've spotted a missing field or wrong data type within 10 seconds of formatting that I would have missed in the minified version.

**Inspecting payloads in bug reports or tickets**: When a teammate pastes a JSON payload into a GitHub issue, Jira ticket, or Slack message, formatting it makes the conversation about the actual data instead of about parsing the text.

**Reviewing configuration files before committing**: When checking config changes, whether it's a package.json, tsconfig.json, or app config, formatted, you're reading.

**Comparing two JSON documents side by side**: When diffing JSON files, formatting both first removes whitespace differences and focuses on actual content changes.

**Writing documentation or examples**: When creating API docs, tutorials, or team guides, always use formatted JSON so readers can follow along.

**Debugging database queries**: When JSON columns or JSONB in PostgreSQL, when you fetch a JSON blob from the database, formatting it makes debugging easier.

**Logging**: When logging JSON to your application, keep logs, you should NOT format JSON when it's being sent over the network or stored long-term in a database. Minified JSON is smaller (sometimes significantly smaller) and more efficient for machines to process. The rule of thumb is: format for humans, minify for machines.

There are many ways to format JSON, each suited to different situations. Here are the tools and workflows I actually use:

**1. Use an online JSON formatter**: This is the fastest way for one-off tasks. Just paste your JSON and get back formatted JSON. This is perfect for when you're in a hurry and don't want to open an editor. Remember: if you're working with sensitive data, use a tool that runs locally in the browser without sending data to a server.

**2. Use your code editor**: VS Code, Sublime Text, WebStorm, and IntelliJ all have excellent built-in JSON support. In VS Code: open a .json file or set the language mode to JSON, then right-click → 'Format Document' or use the keyboard shortcut (Shift+Option+F on Mac, Shift+Alt+F on Windows/Linux). VS Code will even validate as you type and show squiggles under invalid syntax.

**3. Use the command line with `jq`**: The `jq` tool is incredibly powerful and my go-to for working with JSON in the terminal. Basic formatting is just:

cat data.json | jq .

Or you can format and save directly:

jq . data.json > formatted.json

jq also lets you extract specific fields, filter arrays, and transform data — it's worth learning the basics.

**4. Use browser dev tools**: Most browsers let you right-click on a JSON response in the Network tab and view it formatted. In Chrome: Network tab → click request → Response tab → 'Pretty-print' button. In Firefox: Network tab → click request → Response tab → the '{}' icon.

**5. Use Postman/Insomnia/Rest client**: These tools automatically format JSON responses by default. If not, look for the 'Pretty' or 'Format' view option.

**6. Use Python one-liners**: If you have Python installed, you can format JSON from the command line:

python3 -m json.tool data.json

Whichever method you choose, always validate before you format. Invalid JSON will cause most formatters to fail, so validation first will give you a useful error message instead of a generic 'invalid JSON'.

Formatting fails when your JSON isn't valid. Here are the most common validation errors I see, with examples and fixes:

**Problem 1: Trailing commas** — JSON doesn't allow commas after the last item in an object or array. This is probably the #1 mistake developers make when writing JSON by hand.

Invalid:

{
  "name": "John",
  "age": 30,  // This comma is invalid!
}

Valid:

{
  "name": "John",
  "age": 30
}

**Problem 2: Single quotes instead of double quotes** — JSON requires double quotes around keys and string values. Single quotes are fine in JavaScript but not in JSON.

Invalid:

{
  'name': 'John'  // Single quotes won't work
}

Valid:

{
  "name": "John"
}

**Problem 3: Comments** — JSON does not support comments at all. No `// line comments`, no `/* block comments */`. I wish it did, but it's not part of the spec. If you need comments, use a format like YAML or JSON5 for config files instead.

Invalid:

{
  "name": "John",  // User's name
  "age": 30        // User's age
}

Valid:

{
  "name": "John",
  "age": 30
}

**Problem 4: Unquoted keys** — All object keys must be quoted in JSON. In JavaScript you can omit them, but not in JSON.

Invalid:

{
  name: "John",  // Key not quoted
  age: 30
}

Valid:

{
  "name": "John",
  "age": 30
}

**Problem 5: Unescaped characters inside strings** — Certain characters need escaping when they appear inside strings. The most common are newlines (\n), tabs (\t), quotes (\"), and backslashes (\\).

Invalid:

{
  "message": "Hello\nworld",  // Newline needs escaping
  "path": "C:\Users\John"   // Backslashes need escaping
}

Valid:

{
  "message": "Hello\nworld",
  "path": "C:\\Users\\John"
}

**Problem 6: Mixed data types when you expect consistency** — This one won't make your JSON invalid, but it will make formatting reveal a subtle bug. Watch for things like numeric IDs mixing with string IDs.

If formatting fails, validate first. The error message will usually point you to the exact line and column where the problem is. Don't skip the validator — it'll save you time staring at the screen looking for the mistake.

Let's walk through a realistic scenario. You're debugging an e-commerce API and you get this response from the orders endpoint:

{"orderId":"ORD-93847","customer":{"id":8473,"name":"Sarah","email":"[email protected]"},"items":[{"productId":47,"name":"Wireless Headphones","quantity":1,"price":149.99,"options":{"color":"Black","warranty":"2-year"}},{"productId":29,"name":"USB-C Charger","quantity":2,"price":24.99,"options":{"color":"White"}}],"shipping":{"method":"Express","address":{"street":"123 Main St","city":"San Francisco","state":"CA","zip":"94102","country":"US"}},"payment":{"method":"Credit Card","last4":"4242","status":"Processed"},"total":199.97,"status":"Shipped","createdAt":"2026-06-20T14:30:00Z"}

It's valid JSON, but trying to find anything in that wall of text is frustrating. Let's format it:

{
  "orderId": "ORD-93847",
  "customer": {
    "id": 8473,
    "name": "Sarah",
    "email": "[email protected]"
  },
  "items": [
    {
      "productId": 47,
      "name": "Wireless Headphones",
      "quantity": 1,
      "price": 149.99,
      "options": {
        "color": "Black",
        "warranty": "2-year"
      }
    },
    {
      "productId": 29,
      "name": "USB-C Charger",
      "quantity": 2,
      "price": 24.99,
      "options": {
        "color": "White"
      }
    }
  ],
  "shipping": {
    "method": "Express",
    "address": {
      "street": "123 Main St",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94102",
      "country": "US"
    }
  },
  "payment": {
    "method": "Credit Card",
    "last4": "4242",
    "status": "Processed"
  },
  "total": 199.97,
  "status": "Shipped",
  "createdAt": "2026-06-20T14:30:00Z"
}

Now you can quickly see the structure. Notice that there are two items in the order, shipping is going to San Francisco, payment has been processed, and the total is $199.97. You can also see the warranty option on the headphones and the quantity on the chargers.

Formatting doesn't change the data, but it changes everything about how easily you can reason about it. When I'm pairing with teammates, I always format JSON first before we start discussing what's in it — it's just common courtesy.

After working on dozens of teams, I've settled on these practices that make collaboration smoother:

**1. Standardize on indentation**: Pick 2 spaces (not tabs, not 4 spaces) for JSON files in your project. 2 spaces is the most common convention across the JavaScript/Node ecosystem and works well with most tools.

**2. Keep formatted JSON in version control**: Store configuration files formatted in your repo minified JSON for network traffic.

**3. Use Prettier or similar auto-formatting**: Tools like Prettier can automatically format JSON files on save or commit. This eliminates debates about formatting style entirely.

**4. Format before committing changes**: When making edits to JSON files, format them first so the diff shows actual content changes, not just whitespace changes.

**5. Teach your team**: Make sure everyone knows how to format JSON quickly in their editor of choice. It's a small thing, but it saves collective hours over time.

**6. Don't use JSON for config if you need comments**: If you need comments in configuration files, use YAML or JSON5 instead. Don't try to hack comments into JSON with "_comment" fields — it's not worth it.

**7. Validate before formatting**: Always validate first if you're not sure your JSON is valid. The validator will give you a much better error message than the formatter will.