What Is JSON? A 5-Minute Guide to Structure and Common Errors

JSON (JavaScript Object Notation) is the most common way to exchange data on the web. APIs return it, config files use it, logs are full of it. Despite the “JavaScript” in the name, it’s language-independent — Python, Go, Java and virtually everything else can read and write it. Here’s what you need to know in five minutes.

Run it yourself and compare. Paste {"id":42,"tags":["draft","zh"],"meta":{"ok":true,"score":9.5},"note":null} into our JSON Formatter and press Beautify. It returns two-space indentation, the keys in their original order, 9.5 still a number and null still null — nothing is reordered and nothing is coerced. That exact input and output are checked by a script on every build, so if the tool ever changed its behaviour this page would be wrong and we would know.

The building blocks

A JSON document is built from just a few types:

• Object — an unordered set of key/value pairs wrapped in curly braces: { "name": "Ada", "age": 36 }
• Array — an ordered list wrapped in square brackets: [1, 2, 3]
• String — text in double quotes: "hello"
• Number — 42, 3.14, -7 (no quotes)
• Boolean — true or false
• null — an explicit empty value

Objects and arrays can nest inside each other to any depth, which is how JSON represents complex data.

A quick example

{
  "user": "ada",
  "active": true,
  "roles": ["admin", "editor"],
  "profile": { "age": 36, "city": "London" }
}

That’s a single object with a string, a boolean, an array of strings, and a nested object.

The rules that trip people up

Most “invalid JSON” errors come from a small set of mistakes:

1. Trailing commas. [1, 2, 3,] is valid in JavaScript but not in JSON. Remove the comma after the last item.
2. Single quotes. JSON requires double quotes for both keys and string values. {'name': 'Ada'} is invalid; it must be {"name": "Ada"}.
3. Unquoted keys. {name: "Ada"} is a JavaScript object literal, not JSON. Keys must be quoted strings.
4. Comments. JSON has no comment syntax. // like this will cause a parse error.
5. Wrong value types. Numbers and booleans must not be quoted unless you actually want them as strings.

The rules are easier to remember as the errors they produce. We fed four kinds of almost-JSON to our own JSON formatter and recorded exactly what came back. A trailing comma gives

✗ JSON syntax error: Expected double-quoted property name in JSON at position 7 (line 1 column 8) [L1:8]

single quotes give

✗ JSON syntax error: Expected property name or '}' in JSON at position 1 (line 1 column 2) [L1:2]

an unquoted key gives

✗ JSON syntax error: Expected property name or '}' in JSON at position 1 (line 1 column 2) [L1:2]

and a JavaScript undefined gives

✗ JSON syntax error: Unexpected token 'u', "{"a":undefined}" is not valid JSON

Notice that single quotes and an unquoted key produce the same message at the same position: the parser is not looking for a quote type, it is looking for a double-quoted property name and reporting the first place one is missing.

How to fix a broken JSON quickly

When your code throws a parse error, the fastest way to find the problem is to run the document through a validator. Paste it into the JSON formatter: if the syntax is wrong, it points to the approximate location and tells you why. Once it’s valid, click Beautify to see the structure clearly, or Minify to shrink it before sending it over the network.

That is also the fastest way to fix broken JSON: read the position, not the prose. ✗ JSON syntax error: Expected double-quoted property name in JSON at position 7 (line 1 column 8) [L1:8] points at column 8 of line 1 — the character after the last comma — so the fix is at the comma, one position earlier than the report. Parsers report where they gave up, not where you made the mistake, and those are almost never the same character.

When (not) to use JSON

JSON is great for configuration and API payloads. It’s less ideal for very large datasets (streaming formats or binary formats are more efficient) or for documents that need comments (YAML or TOML are friendlier there). But for the vast majority of web work, JSON is the lingua franca — and now you can read it fluently.

Ready to tidy up some JSON? Try the free JSON formatter — it runs entirely in your browser, so your data never leaves your device.