Understanding JSON: A Practical Guide
Developer Tools - 4 min read - Published 2026-08-27 - Updated 2026-10-19
JSON (JavaScript Object Notation) is the format almost every web API speaks today, including APIs written in languages that have nothing to do with JavaScript. Configuration files, log lines, browser storage and data exports all use it. It won out over XML for a simple reason: it maps directly onto the data structures programmers already work with - objects, arrays, strings, numbers, true/false and null - with far less punctuation.
This guide covers what valid JSON looks like, the rules that catch people out, how to read a parser's error message, and a few traps that cause bugs even when the JSON is technically valid.
The six kinds of value
Everything in JSON is one of six types. An object is a set of key-value pairs in curly braces: {"name": "Ana", "age": 34}. An array is an ordered list in square brackets: [1, 2, 3]. A string is text in double quotes. A number is written in ordinary decimal form, optionally with a fraction or exponent, such as 42, -3.5 or 6.02e23. Then there are the literals true, false and null.
Objects and arrays can contain each other to any depth, which is how JSON describes complex data: an order object can hold a customer object and an array of item objects, each with its own fields. The formal definition is short; the current standard is RFC 8259.
The rules are stricter than they look
JSON looks like a JavaScript object literal, which is exactly why people get tripped up. It isn't one. Every key must be a string in double quotes - {name: "Ana"} and {'name': 'Ana'} are both invalid. Single quotes aren't allowed for strings either.
Trailing commas are forbidden: [1, 2, 3,] and {"a": 1,} are invalid, even though many programming languages accept them. Comments don't exist at all; there's no // or /* */ in JSON. Numbers can't have leading zeros (007 is invalid) or a leading plus sign, and there's no way to write NaN, Infinity or undefined. If a value is missing, use null or leave the key out.
Inside strings, a few characters must be escaped with a backslash: the double quote (\"), the backslash itself (\\), and control characters such as a line break (\n) or tab (\t). Any character can also be written as \u followed by four hex digits, for example \u00e9 for é.
Reading a parser error
Parser errors usually point to where the parser gave up, not where the mistake is. A message such as "Unexpected token } in JSON at position 42" often means there's a trailing comma just before position 42: the parser saw a comma, expected another value, and found a closing brace instead.
A worked example: {"id": 1, "tags": ["a", "b",], "ok": true}. The error appears at the ] because of the comma after "b". Similarly, "Unexpected token ' " almost always means single quotes, and "Unexpected end of JSON input" means the text was cut off - a missing closing bracket, or a response that didn't arrive completely.
A formatter makes these problems easy to spot. Once the JSON is indented, an unclosed bracket or a value in the wrong place stands out, and a validator can point to the exact line.
Traps in valid JSON
Big numbers: JSON itself puts no limit on numbers, but JavaScript and many other languages store them as 64-bit floating point, which can only represent whole numbers exactly up to 9,007,199,254,740,991. Larger IDs are silently rounded when parsed, so two different IDs can end up looking identical. APIs that use very large IDs often send them as strings for this reason.
Dates: JSON has no date type. The common convention is an ISO 8601 string such as "2026-10-19T14:30:00Z", where the Z means UTC. Sending local times without a time zone, or as numbers of seconds in one system and milliseconds in another, is a frequent source of off-by-hours bugs.
Duplicate keys: {"a": 1, "a": 2} is technically allowed, but what a parser does with it isn't defined; most keep the last value. Avoid duplicates rather than relying on any behavior.
JSON's relatives
Because plain JSON has no comments, some tools use extended formats. JSONC (JSON with comments) is used for editor settings files, and JSON5 allows comments, trailing commas and unquoted keys. They're convenient for files people edit by hand, but a strict JSON parser rejects them, so don't send them to an API that expects JSON.
JSON Lines (one JSON object per line) is popular for logs and large exports, because a file can be read one line at a time instead of all at once. And JSON Schema is a separate standard for describing what a valid document must contain - required fields, types and allowed values - which goes beyond checking that the syntax is correct.
Formatting vs minifying
Formatted (pretty-printed) JSON adds line breaks and indentation so people can read it. Minified JSON removes all unnecessary whitespace so it's smaller to send. Both contain exactly the same data, and every parser reads both. A common workflow is to keep minified JSON in transit and storage, and format it whenever a person needs to read or debug it.