JSON for people who hate JSON — a practical guide for non-engineers

What JSON is

JSON is text, organised as a tree of name/value pairs. The whole thing lives inside curly braces. Each pair is a string in double quotes, a colon, and a value. Values can be strings, numbers, booleans, null, arrays (in square brackets), or other objects. That is the entire specification. It is intentionally tiny.

How to read a JSON file

Start at the top. The whole thing is one object. Read the field names left-to-right. When you hit a value that is itself an object or array, you are recursing — open a new mental "scope", read the contents, close it. Pretty-printing (adding indentation and newlines) makes the structure obvious; this site's JSON formatter does it in one click.

The four errors you will hit

1) Trailing comma (a comma after the last item in an object or array) — invalid in JSON, even though it is valid in JavaScript. 2) Single quotes instead of double quotes — JSON requires double quotes for strings. 3) Unquoted keys — keys must be in double quotes, even if they look like numbers. 4) Comments — JSON does not support comments. If you want comments, you want JSON5 or YAML, not JSON.

JSON vs YAML vs TOML

YAML is JSON's indentation-based cousin, popular for config files (Kubernetes, GitHub Actions, Ansible). TOML is the newer alternative, designed to be unambiguous and easy to parse (Rust's Cargo, Python's pyproject.toml). JSON is the most portable, the most widely supported, and the one most APIs use. If you control the format, pick the one your tooling supports; if you are sending data over the wire, JSON is the default.

What this site gives you

A JSON beautifier and validator that highlights errors inline. A JSON/YAML studio for converting between formats. A diff tool for comparing two JSON structures. All three run in your browser, none of them upload your data anywhere.