What Is JSON and Why You Should Always Format It

Open any modern API. Inspect any web page's network tab. Read any cloud platform's deployment logs. The data flowing through is, almost certainly, JSON: JavaScript Object Notation. It is the lingua franca of the post-2010 web.

But ask a working developer "what is JSON, exactly?" and the answers vary. Some say "it's just JavaScript objects." (No.) Some say "it's a serialization format." (Closer.) Some say "it's the thing that breaks when someone forgets a comma." (Accurate.)

This post is the answer I wish someone had given me when I was twelve hours into debugging a JSON parser at 2 AM. We'll cover what JSON formally is, what it is not, and why formatting it correctly matters even when humans never read it.

What JSON formally is

JSON is a text-based data interchange format defined by RFC 8259. It is:

1. Plain text. UTF-8 encoded by default. You can read it. You can edit it in vim. You can email it.
2. Structured. Every valid JSON document is exactly one of these seven things:
   • An object ({}): unordered name/value pairs
   • An array ([]): ordered list of values
   • A string ("..."): UTF-8 text in double quotes
   • A number (42, 3.14, -1.5e10): like JavaScript Number
   • The literal true
   • The literal false
   • The literal null
3. Recursive. Objects and arrays can contain any JSON value: including more objects and arrays. This is how complex data fits in a flat text format.
4. Strict. Every byte matters. Trailing commas? Invalid. Single quotes? Invalid. Comments? Invalid. JSON is unforgiving by design.

Here is a complete, valid JSON document:

{
  "user": {
    "id": 42,
    "name": "Ada Lovelace",
    "active": true,
    "joined": "1843-12-10",
    "tags": ["mathematician", "founder"]
  },
  "request_id": "req_7sXy9k3pQ",
  "version": 2
}

That's it. Nothing more. JSON is fundamentally simple, which is why it won.

What JSON is NOT

This is where most confusion lives.

JSON is not JavaScript. JavaScript objects can have unquoted keys, single-quoted strings, trailing commas, comments, function values, undefined, NaN, dates, and circular references. JSON has none of those. Every JSON document is also valid JavaScript (it's a subset), but the reverse is not true.

JSON is not a query language. You cannot ask "give me the user whose ID is 42" of a JSON document. You parse it into your language's native data structure and query it from there. (Or use JSONPath, which is a separate spec.)

JSON is not human-readable by accident. It's human-readable because someone formatted it. Minified JSON like {"user":{"id":42,"name":"Ada"}} is technically valid but unreadable to anyone scanning it.

JSON is not the most efficient format. It's text, with lots of repeated key names, in a notoriously slow-to-parse syntax. For high-throughput systems people use Protocol Buffers, MessagePack, Avro, or CBOR. JSON wins on human readability and tool ubiquity, not raw speed.

Why formatting matters even for machines

Here is the most important thing in this entire post: formatting JSON is not just for humans.

Yes, indented JSON is easier for you to read. But there are concrete machine reasons to format JSON in production logs, in error messages, in version-controlled config files, and in API responses.

Reason 1: Diff-ability

Compare two minified JSON documents and you get a single mile-wide line of red and green characters. Nobody can review that. Compare two formatted documents and git diff shows exactly which fields changed. Code review becomes possible.

   "config": {
-    "timeout": 30,
+    "timeout": 60,
     "retries": 3
   }

Versus:

-{"config":{"timeout":30,"retries":3}}
+{"config":{"timeout":60,"retries":3}}

The diff is the same information, but only one is reviewable.

Reason 2: Error location

When parsing fails, the error message says something like Unexpected token at position 247. In a minified document that's a needle in a haystack. In a formatted document that's "line 17, column 3." Use the JSON formatter before you debug, every parser already gives you exact line+column locations on formatted input.

Reason 3: Cognitive load on production debugging

You will, at some point, paste a JSON payload from a production log into a tool to figure out what went wrong. If that payload is minified, you will spend 30 seconds finding the field you care about. If it's formatted, you spend 3 seconds. Multiply by the number of incidents in a year.

Reason 4: AI assistant readability

Tools that summarize errors, parse stack traces, or feed JSON into LLMs all work better with formatted input. Even Claude and GPT parse formatted JSON more reliably than minified, because the structure is visually clear in the token stream.

When NOT to format JSON

There is exactly one situation where you minify: shipping bytes over the network. APIs send minified JSON. Webhooks deliver minified JSON. SSE/WebSocket frames carry minified JSON. Every byte saved is a microsecond shaved off page load.

But the moment that minified payload lands in a log, an error report, or a user-facing inspector, format it. Browsers' devtools auto-format. Postman auto-formats. Your error tracker should auto-format. If yours doesn't, paste it into an online formatter before debugging.

The four most common JSON mistakes

Even after twenty years, devs still hit the same four errors. Quick reference:

1. Trailing comma. {"a": 1,}: invalid. Remove the final comma.
2. Single quotes. {'a': 1}: invalid. Use ".
3. Unquoted keys. {a: 1}: invalid. Wrap keys in ".
4. JavaScript values. undefined, NaN, Infinity: none are valid JSON. Use null or omit the key.

For the full list of validation errors and how to fix each, see The 10 Most Common JSON Validation Errors.

When you outgrow plain JSON

JSON has known limitations. As you scale, you'll hit them:

• No comments. Configs become hard to maintain. Migrate to YAML for human-edited configs (use our YAML to JSON converter) or use JSON5/JSONC where supported.
• Number precision. JSON numbers map to JavaScript Number, which is a 64-bit float. Integers above 2⁵³ lose precision. Use strings for IDs that exceed safe range: Twitter learned this the hard way with tweet_id.
• No dates. JSON has no date type. Convention: ISO 8601 strings ("2026-04-27T10:00:00Z"). Validate with our Timestamp Converter.
• No binary. JSON cannot carry raw bytes. Convention: Base64-encode and put the string in a JSON field.
• Verbosity at scale. A million records with 20 fields each is a lot of redundant key strings. For high-throughput analytics use Parquet, not JSON.

A tiny mental model

If you take only one thing from this post: JSON is a tree of values where every value is one of seven specific shapes. Objects and arrays are the branches. Everything else is a leaf. There are no exceptions, no surprises, and no hidden behaviors.

That tree-of-values mental model is what makes JSON formatters work. It's what makes JSON diff tools work. It's what makes JSONPath queries work. The data has structure, formatting just makes that structure visible.

Format your JSON. Always. Even when nobody is watching. Especially then.

Further reading

• The 10 Most Common JSON Validation Errors (and How to Fix Them)
• Comparing JSON Structurally (Not Just as Strings)
• YAML vs JSON: Which Should You Use for Config?
• RFC 8259: The JSON Data Interchange Format (the actual spec, surprisingly readable)

Format some JSON in our JSON Formatter: it runs entirely in your browser, so the JSON you paste never leaves your device.