Understanding JSON Formatting: A Practical Guide

JSON (JavaScript Object Notation) has become the default format for moving data between a server and a browser, between two APIs, or into a configuration file — and for good reason: it's lightweight, human-readable, and every mainstream programming language can parse it natively. But its simplicity hides a strict, unforgiving syntax. A single stray comma can take down an entire API response. This guide covers the actual rules, the mistakes that break them most often, and the difference between formatting and minifying your JSON.

The building blocks of JSON

Every JSON document is built from just six things, nested inside each other however deep you need:

• Objects — an unordered set of key-value pairs, wrapped in curly braces: {"name": "Ada", "age": 34}
• Arrays — an ordered list of values, wrapped in square brackets: ["red", "green", "blue"]
• Strings — always wrapped in double quotes, never single quotes: "hello"
• Numbers — written plainly, no quotes, no leading zeros: 42, 3.14, -7
• Booleans — the bare (lowercase, unquoted) words true or false
• Null — the bare word null, representing "no value"

Object keys are always strings in double quotes — {"key": "value"}, never {key: "value"} or {'key': 'value'}. This trips up more people than any other rule, mostly because JavaScript object literals (which look almost identical) do allow unquoted keys and single-quoted strings. JSON does not.

A complete, valid example

{
  "name": "Ada Lovelace",
  "active": true,
  "score": 98.5,
  "tags": ["mathematician", "writer"],
  "manager": null,
  "address": {
    "city": "London",
    "country": "UK"
  }
}

Notice the nesting: address is an object nested inside the outer object, and tags is an array of strings. JSON has no depth limit — objects and arrays can nest inside each other as many levels as the data actually needs.

A realistic API response

Real-world JSON is almost always an array of objects with a consistent shape, since that's what maps cleanly onto a database table or a list rendered in an application. A typical API response listing users might look like this:

{
  "users": [
    { "id": 1, "name": "Ada Lovelace", "role": "admin" },
    { "id": 2, "name": "Grace Hopper", "role": "editor" },
    { "id": 3, "name": "Katherine Johnson", "role": "viewer" }
  ],
  "total": 3,
  "page": 1
}

This shape — an outer object holding an array of uniformly structured records, plus some metadata about the collection like total and page — is by far the most common pattern in REST APIs, and it's exactly the shape that converts cleanly to a spreadsheet: each object in the users array becomes one row.

Escaping special characters inside strings

Because double quotes delimit every JSON string, a string that needs to contain a double quote has to escape it with a backslash: "She said \"hello\"". A handful of other characters follow the same escaping rule:

• \" — a literal double quote
• \\ — a literal backslash
• \n — a newline
• \t — a tab character
• \uXXXX — any Unicode character by its four-digit hex code, e.g. é for "é"

Forgetting to escape a backslash is a particularly common source of broken JSON when values contain Windows-style file paths (C:\Users\name) or regular expressions — both need every backslash doubled before they're valid inside a JSON string.

JSON vs. XML

Before JSON became the default, XML filled the same role — and it's still common in older enterprise systems, RSS feeds, and SOAP APIs. The practical differences explain why JSON largely displaced it for new APIs:

• Verbosity. XML repeats each tag name in both an opening and closing form (<name>Ada</name>), while JSON states the key once ("name": "Ada") — meaningfully more compact for the same data.
• Data types. XML is fundamentally text — every value is a string, and distinguishing a number or boolean from a string requires external convention or a schema. JSON has numbers, booleans, and null as first-class types built into the syntax itself.
• Native language support. JSON parses directly into native objects and arrays in JavaScript with zero library code (hence the name), and every other mainstream language now ships a JSON parser in its standard library. XML typically needs a dedicated parsing library and more code to traverse.

XML retains real advantages for documents with mixed content and attributes (which is why it's still standard for markup-heavy formats), but for pure data interchange, JSON's compactness and native typing are why it became the default.

Validating structure with JSON Schema

Plain JSON validation only confirms a document is syntactically well-formed — it doesn't check that a "users" array actually contains objects with the fields your application expects. JSON Schema is a separate specification for describing that expected shape (required fields, data types, allowed value ranges) so a document can be validated against a contract, not just against basic syntax. It's worth knowing this distinction exists, even for straightforward day-to-day formatting: syntax validation catches broken JSON, but only schema validation catches JSON that parses successfully yet is still missing the fields your code needs.

The most common syntax errors

Almost every "invalid JSON" error traces back to one of these five mistakes:

1. Trailing commas. {"a": 1, "b": 2,} is invalid — that comma after the last value has nothing after it to separate. JSON has no tolerance for trailing commas anywhere, in objects or arrays.
2. Single-quoted strings. {'name': 'Ada'} is invalid. JSON requires double quotes, full stop.
3. Unquoted keys. {name: "Ada"} is invalid — every key needs double quotes around it, even if it looks like a valid identifier.
4. Comments. JSON has no comment syntax at all — no //, no /* */. Many config-file formats that look like JSON (like JSONC, used by some editors) allow comments, but strict JSON parsers will reject them.
5. Mismatched or missing brackets. Every { needs a matching }, and every [ needs a matching ]. In deeply nested documents, a single missing closing brace can be genuinely hard to spot by eye.

The fastest way to find any of these is to run the document through a formatter/validator rather than scanning it manually — it will point to the exact line and character where parsing failed.

Formatting vs. minifying

These are opposite transformations of the same underlying data, used for different purposes:

• Formatting (also called "pretty-printing" or "beautifying") adds indentation and line breaks so a human can actually read the structure. Use this while debugging, reviewing API responses, or editing config files by hand.
• Minifying strips every unnecessary space, tab, and line break, leaving the smallest possible payload. Use this for anything sent over the network in production — a minified JSON response is smaller to transmit and marginally faster to parse, and neither change affects what the data actually contains, since whitespace outside of strings carries no meaning in JSON.

A typical workflow: fetch a compact, minified API response, run it through a formatter to actually read and debug it, then minify your own config or payload again before shipping it.

Converting JSON to and from other formats

JSON isn't the only structured data format you'll run into. Spreadsheets and databases often export as CSV (comma-separated values) — flat, tabular data with no nesting — while JSON supports arbitrary nesting. Converting between the two is common when, for example, you need to load an API's JSON response into a spreadsheet, or turn spreadsheet rows into JSON records for an API request. The conversion works cleanly when your JSON is a flat array of objects with consistent keys; deeply nested JSON needs to be flattened first, since a spreadsheet row has no concept of a nested object.

Frequently asked questions

Why does my JSON fail to parse even though it "looks right"?

The most common invisible cause is a trailing comma left over from editing — adding a new last field and forgetting to remove the comma after the field that used to be last, or deleting the last field and leaving a dangling comma on the one before it. Because trailing commas are easy to miss by eye but always invalid in JSON, running the document through a validator rather than proofreading manually is the reliable fix.

Can JSON have comments for documentation?

No — the JSON specification has no comment syntax at all, by design, to keep parsers simple and unambiguous across every implementation. If you need documented configuration, either keep the documentation in a separate README, use a JSON-superset format that explicitly allows comments (like JSONC or JSON5) with a parser that supports it, or switch to YAML, which does support comments natively.

Does key order matter in a JSON object?

Per the specification, no — object keys are formally unordered, and a compliant parser isn't required to preserve the order keys were written in. In practice, most parsers do preserve insertion order for convenience, but you shouldn't rely on it for anything your program's correctness depends on; if order matters, use an array instead of relying on object key order.

What's the maximum size of a JSON document?

The specification itself sets no size limit — the practical limit comes from whatever is parsing it (available memory, or a specific API's request size cap) rather than JSON as a format. Very large JSON documents are usually better streamed and parsed incrementally rather than loaded and parsed all at once.

Work with your JSON

DocNectar's JSON Formatter validates and pretty-prints any JSON document, pointing out exactly where a syntax error occurs. When you're ready to ship, the JSON Minifier strips it back down to the smallest valid payload. For moving between tabular and JSON data, the JSON to CSV and CSV to JSON converters handle the conversion in either direction.