Developer

Why JSON Formatting Matters (And How to Fix Broken JSON)

📅 July 2026 ⏱ 6 min read 🔧 Related tool: JSON Formatter & Validator

JSON is everywhere. It's how APIs return data, how configuration files are structured, and how databases like MongoDB store documents. If you work in software development, data analysis, or even just plug around with web APIs, you'll encounter JSON constantly.

Despite being designed to be simple and human-readable, JSON has strict syntax rules — and breaking any of them causes the whole thing to fail silently or throw a cryptic parse error. This guide covers what those rules are, the mistakes that trip people up most often, and how to debug broken JSON quickly.

What JSON Is and Why It Exists

JSON stands for JavaScript Object Notation. It was originally derived from JavaScript's object syntax, but it's now a language-agnostic data format used across virtually every programming language. Its appeal is simple: it's readable by humans and easy to parse by machines.

A JSON document is made up of two structures: objects (key-value pairs surrounded by curly braces) and arrays (ordered lists surrounded by square brackets). Everything else — strings, numbers, booleans, and null — are the values those structures can hold.

The Strict Rules JSON Enforces

Unlike JavaScript, JSON has no flexibility. Every rule is absolute:

Keys must be strings in double quotes. Single quotes are not valid. Unquoted keys are not valid.
String values must also use double quotes. Not single quotes.
No trailing commas. The last item in an object or array cannot have a comma after it.
No comments. JSON does not support comments of any kind — no //, no /* */.
Numbers must be actual numbers. Hex values, Infinity, and NaN are not valid JSON.
Boolean values are lowercase. true and false, not True or False.

The Most Common JSON Mistakes

1. Trailing Commas

This is probably the single most common JSON error, especially for JavaScript developers who are used to trailing commas being fine in JS objects.

// Invalid JSON — trailing comma after last item
{
  "name": "Alice",
  "age": 30,  ← this comma is the problem
}

// Valid JSON
{
  "name": "Alice",
  "age": 30
}
            

2. Single Quotes Instead of Double Quotes

Both keys and string values must use double quotes. Single quotes will cause a parse error in any strict JSON parser.

// Invalid
{ 'name': 'Alice' }

// Valid
{ "name": "Alice" }
            

3. Forgetting to Escape Special Characters

If a string value contains a double quote, backslash, or certain control characters, they need to be escaped with a backslash.

// Invalid — unescaped quote inside string
{ "message": "She said "hello" to me" }

// Valid — escaped quotes
{ "message": "She said \"hello\" to me" }
            

4. Mismatched Brackets

Opening a { and closing with a ] (or vice versa) is a parse error. With deeply nested JSON this is easy to miss by eye — a formatter that shows structure visually makes it obvious.

Why Pretty-Printing Matters

JSON can be written as a single line ("minified") or spread across multiple lines with indentation ("pretty-printed"). Minified JSON is smaller and faster to transfer, but nearly impossible to read. When you're debugging an API response or editing a config file, pretty-printing makes the structure immediately clear.

                Rule of thumb: Use minified JSON in production (smaller payload). Use pretty-printed JSON whenever a human needs to read or edit it. A formatter converts between the two in one click.
            

How to Debug JSON Fast

When you get a JSON parse error, the error message usually tells you the line and character position of the problem. Here's a reliable debugging workflow:

Paste the JSON into a formatter/validator. Most will highlight the exact problem location.
Check for trailing commas first — they account for a large share of JSON errors.
Check that all strings use double quotes.
Count your opening and closing braces and brackets — they must match.
If the JSON came from an API, check whether it's actually HTML (an error page) rather than JSON. This is a common gotcha when an API call fails.

JSON vs. Related Formats

It's worth knowing where JSON fits among similar data formats:

YAML is more human-friendly (supports comments, less punctuation) but more error-prone due to indentation sensitivity. Common in config files (Docker, Kubernetes, GitHub Actions).
XML is verbose but has strong schema validation support. Still widely used in enterprise systems and certain APIs (SOAP).
TOML is popular for configuration files (Rust's Cargo, Python's pyproject.toml) and is very readable.
CSV is simpler but only handles flat, tabular data — no nesting.

For most API communication and modern web applications, JSON is the right default choice.

Frequently Asked Questions

Can I add comments to JSON?

No — standard JSON does not support comments. If you need a config file format that supports comments, consider YAML or TOML instead. Some tools like VS Code accept a variant called JSON with Comments (JSONC) for their own config files, but this is not valid standard JSON.

What's the difference between JSON.parse() and JSON.stringify()?

In JavaScript, JSON.parse() converts a JSON string into a JavaScript object. JSON.stringify() does the reverse — converts a JavaScript object into a JSON string. The second argument to stringify can control indentation: JSON.stringify(obj, null, 2) pretty-prints with 2-space indentation.

Why does my JSON validator say the file is valid but my app still fails?

The JSON might be syntactically valid but semantically wrong — the right structure but wrong data types, missing required fields, or values outside an expected range. A JSON validator only checks syntax. If you need schema validation (ensuring the data matches a specific structure), look into JSON Schema.

Paste your JSON to format, validate, and fix syntax errors — instantly, in your browser.

Open JSON Formatter →