How to format and validate JSON: a developer's guide

JSON is everywhere: API responses, configuration files, logs, message queues, request payloads, database columns. For such a simple format, it’s surprising how often we hit trouble with it — a missing comma breaks a deployment, an extra whitespace character makes two files “different” when they should be identical, a deeply nested structure is impossible to debug because nobody indented it.

Here’s a practical guide to working with JSON cleanly: what the format actually requires, how to make it readable, how to validate it, and the small habits that stop JSON bugs from making it to production.

What JSON actually allows

The JSON spec is deliberately tiny. A JSON document is one of:

• An object: { "key": value, ... }
• An array: [ value, ... ]
• A string: "text" (always double-quoted, never single-quoted)
• A number: 42, 3.14, -2.5e10
• A boolean: true or false
• null

That’s it. No comments. No trailing commas. No unquoted keys. No single-quoted strings. No undefined. No NaN or Infinity. No functions.

If you’ve ever wondered why a JSON parser rejected your “obviously valid” file, it’s usually one of these:

{
  "name": "Alice",
  "age": 30, // ← comment: NOT valid JSON
  "email": 'alice@...', // ← single quotes: NOT valid JSON
  role: "admin", // ← unquoted key: NOT valid JSON
  "active": true, // ← trailing comma: NOT valid JSON
}

The formats that do allow these relaxations are JSON5 (allows comments, trailing commas, unquoted keys) and JSONC (JSON with Comments, used by VS Code config files). They’re supersets of JSON but require specialised parsers.

Formatting rules that make JSON readable

Minified JSON looks like this:

{"users":[{"id":1,"name":"Alice","roles":["admin","editor"]},{"id":2,"name":"Bob","roles":["viewer"]}]}

Formatted JSON looks like this:

{
  "users": [
    {
      "id": 1,
      "name": "Alice",
      "roles": ["admin", "editor"]
    },
    {
      "id": 2,
      "name": "Bob",
      "roles": ["viewer"]
    }
  ]
}

Same data, completely different readability.

The formatting rules that matter: indentation of 2 spaces is by far the most common convention — some codebases use 4, tabs are rare, but be consistent within a project. One key per line inside objects, one item per line inside arrays for arrays of non-trivial content. Space after the colon, no space before: "key": value. Arrays of primitives on one line when short is fine. Arrays of objects on multiple lines always — they get unreadable fast otherwise.

The JSON Formatter applies all of this automatically when you click Format.

Validating JSON: what to look for

1. Missing or extra comma

By far the most common. Syntactically invalid JSON almost always has a comma issue.

{
  "a": 1,
  "b": 2 ← missing comma
  "c": 3
}

The parser blames the line after the missing comma, which can be misleading.

2. Unclosed string

A stray newline inside a string, or a missing closing quote:

{ "name": "Alice
}

JSON does not allow literal newlines inside strings. Escape them as \n.

3. Mismatched brackets

One extra } or ] anywhere in a file:

{
  "users": [{"name": "Alice"}]}
}

Most parsers report the first bracket that doesn’t match, which may be far from the actual error.

4. Invalid number

JSON numbers follow strict rules: no leading +, no leading zeros (except 0.x), no 1. without a trailing digit, no .5 without a leading zero.

{ "a": +5, "b": 07, "c": 1., "d": .5 } ← all invalid

5. Escaped characters in strings

Backslashes and quotes inside strings must be escaped:

{ "path": "C:\Users\Alice" }   ← invalid (backslash isn't escaped)
{ "path": "C:\\Users\\Alice" } ← valid

6. Duplicate keys

Technically the JSON spec says duplicate keys are “allowed but unadvised.” In practice, most parsers silently take the last value. This is almost always a bug.

{ "name": "Alice", "name": "Bob" }

How to format and validate in practice

The fastest workflow for most developers: paste the suspect JSON into a formatter, click Format, read the error message if it rejects, check the line number (usually close to but not exactly at the real problem).

The JSON Formatter uses the browser’s built-in JSON.parse — the same parser used by every Node.js API and web service — so any error message you see is exactly what a real JSON API would emit.

The minify / format toggle

Formatters usually have two buttons:

• Format (or Beautify, Pretty-print): adds whitespace and indentation for human reading
• Minify (or Compact): removes all unnecessary whitespace

Minified JSON is used when you care about byte size — sending over the wire, storing in a database, embedding in a URL. Functionally identical to formatted JSON but noticeably smaller for large documents.

Formatted: 1,240 bytes
Minified: 680 bytes (-45%)

For production API responses, always minify. For config files, logs, and anything humans will read, always format.

Tools beyond the formatter

Once your JSON is formatted and valid, you often need to do more. Worth knowing:

JSON schema — a way to define what fields a valid document must have, with types and constraints. If you have a JSON shape you want to enforce across multiple documents, write a schema and validate against it.

JMESPath / jq — query languages for extracting or transforming JSON. jq is the de-facto command-line tool.

JSON diff — tools that show what changed between two JSON documents, more usefully than a text diff.

Quick reference cheatsheet

Need	What to do
Make JSON readable	Format with 2-space indent
Shrink for transport	Minify
Find a syntax error	Paste into a formatter, note error location
Check if two documents are “the same”	Minify both and compare byte-for-byte, or use a proper JSON diff
Add structure validation	Use JSON Schema
Store in a URL or cookie	Minify and URI-encode

A workflow tip worth keeping

Never paste raw JSON into an email, chat message, or issue tracker without first formatting it. Minified JSON in a GitHub issue is borderline unreadable and wastes the reader’s time. Thirty seconds in a formatter turns a wall of text into a readable structure.

And when debugging a real API response, pipe it through a formatter before you try to understand it. This one habit saves hours of squinting at unindented output.

---

The JSON Formatter runs in your browser — no uploads, no server round-trips, nothing is logged anywhere. Paste JSON in, click Format or Minify, click Copy, done. JSON is everywhere, but working with it cleanly is still a skill that pays off — cleaner commits, clearer bugs, faster reviews.