A beginner's guide to JSON (with real-world examples)

If you've spent any time near modern software, you've bumped into JSON. It's the format APIs return, the format most modern config files use, and the format your browser stores nearly everything in. Understanding it takes maybe ten minutes, and it pays dividends every time you need to read an error message, poke at a settings file, or work with a REST API.

JSON stands for JavaScript Object Notation. Despite the name, it's language-agnostic — every mainstream programming language can read and write it. The format was designed to be human-readable, which was a big deal when it emerged as an alternative to the much heavier XML.

There are only six data types you need to know: strings (in double quotes), numbers (no quotes), booleans (true or false), null, arrays (in square brackets), and objects (in curly braces). Every JSON document is built from these primitives, nested however deep the data requires.

A tiny example: {"name": "Ada", "age": 36, "skills": ["maths", "programming"]}. That's an object with three fields — a string, a number, and an array of strings. Notice the double quotes around every key and every string value; single quotes are not valid JSON and will trip you up if you're coming from Python or JavaScript syntax.

The three most common mistakes are trailing commas, single quotes, and unescaped characters. JSON does not allow a comma after the last item in a list or object. It does not allow single quotes anywhere. And every literal backslash inside a string must be doubled. A good JSON validator will catch all three in seconds.

In practice most people don't write JSON by hand — they generate it from an object in code. But you will read it constantly, especially when debugging an API. Learning to trace nested objects visually saves a lot of guessing: match every opening brace to its closing one, and you'll always know which level of the structure you're looking at.

For anything longer than a few lines, use a JSON formatter (there's one on this site). Pretty-printed JSON with proper indentation is far easier to scan than the minified single-line version most APIs return. Minified JSON is smaller to transmit, which is why it's the default over the wire, but you should always format it before trying to read it.

Some real-world places JSON appears: package.json in a Node.js project, tsconfig.json in a TypeScript project, the response body of nearly every REST API, config files for VSCode, and localStorage entries in your browser. Being able to open one of these and immediately see the structure is a skill that pays off constantly.

One last tip: JSON doesn't have comments. If you need annotated configuration, use JSONC or JSON5 (both supported by many tools) or store comments in a separate README. Trying to add a // to a strict JSON parser will cause a syntax error every time.