JSON is the lingua franca of modern web APIs. You'll find it in REST responses, configuration files, package manifests, and database documents. Its syntax looks simple — and mostly it is — but a handful of rules trip up beginners in ways that aren't always obvious from error messages.
Let's walk through everything you need to know to read and write JSON confidently.
What JSON Actually Is
JSON stands for JavaScript Object Notation. It was derived from JavaScript object literal syntax, but it's a language-independent format. Every major programming language has JSON parsing built in or available as a standard library.
At its core, JSON is just a way to represent structured data as text — and that text-safe property is what makes it so useful for sending data over networks, storing in files, and embedding in other documents.
The Six Data Types
JSON supports exactly six data types. No more, no less.
Strings are wrapped in double quotes — always double quotes, never single. The value "hello" is valid. The value 'hello' is not JSON.
Numbers are unquoted numeric values. Both integers and decimals are allowed: 42, 3.14, -7. Scientific notation like 6.02e23 is also valid.
Booleans are the literal lowercase values true and false. Capitalized versions (True, False) are not valid JSON — that's Python territory.
Null is the literal null. It represents an intentional absence of value.
Objects are collections of key-value pairs, wrapped in curly braces. Keys must be strings (in double quotes), and key-value pairs are separated by commas.
Arrays are ordered lists of values, wrapped in square brackets. Values are comma-separated and can be any valid JSON type.
{
"name": "Alice",
"age": 30,
"isActive": true,
"score": null,
"tags": ["admin", "editor"],
"address": {
"city": "New York",
"zip": "10001"
}
}Objects and Arrays in Depth
Objects and arrays can contain any JSON value — including other objects and arrays. This nesting is what makes JSON powerful for representing real-world data structures.
Object rules
Every key must be a double-quoted string. The value can be any JSON type. Pairs are comma-separated, with no comma after the last one (more on this in a moment).
{
"firstName": "Bob",
"lastName": "Smith",
"age": 25
}Array rules
Arrays preserve order. Elements can be of mixed types — a single array can contain strings, numbers, objects, even other arrays.
["text", 42, true, null, {"nested": "object"}, [1, 2, 3]]In practice, arrays usually contain elements of the same type, but JSON itself doesn't enforce this.
Common Syntax Mistakes
These are the errors you'll make at least once. Probably more than once.
Trailing commas
This is the single most common JSON mistake. Most programming languages allow a trailing comma on the last item in a list. JSON does not.
// INVALID — trailing comma after last property
{
"name": "Alice",
"age": 30,
}
// VALID
{
"name": "Alice",
"age": 30
}JavaScript developers are especially prone to this because JS objects and arrays accept trailing commas just fine.
Single quotes
Keys and string values must use double quotes. Single quotes are a JavaScript thing, not a JSON thing.
// INVALID
{
'name': 'Alice'
}
// VALID
{
"name": "Alice"
}Comments are not allowed
JSON has no comment syntax. There's no // or /* */. If you find a JSON file with comments, it's probably a superset format like JSON5 or JSONC (used by VS Code configs), not standard JSON.
If you need to document fields in a config file, some teams add a "_comment" key as a workaround — ugly, but technically valid.
Undefined is not a type
undefined is a JavaScript concept with no equivalent in JSON. If you try to serialize a JavaScript object that contains undefined values, JSON.stringify() will silently drop those keys.
Numbers have limits
JSON numbers are technically unlimited in specification, but parsers are another story. Most environments map JSON numbers to 64-bit IEEE 754 floats, which means integers larger than Number.MAX_SAFE_INTEGER (9007199254740991) may lose precision. If you're dealing with large IDs (common in distributed systems), use strings instead.
Nesting and Depth
You can nest objects and arrays as deeply as you need. Here's a more realistic API response shape:
{
"user": {
"id": 1042,
"profile": {
"displayName": "Alice",
"avatarUrl": "https://example.com/avatar.jpg"
},
"roles": ["admin", "editor"],
"preferences": {
"theme": "dark",
"notifications": {
"email": true,
"push": false
}
}
},
"meta": {
"requestId": "a1b2c3d4",
"timestamp": "2024-01-15T10:30:00Z"
}
}Deep nesting is valid JSON, but it can be a design smell in an API. If you're five levels deep, it might be worth flattening the structure.
Pretty-Printed vs Minified
JSON doesn't care about whitespace. These two are semantically identical:
{"name":"Alice","age":30}{
"name": "Alice",
"age": 30
}The first is minified — no unnecessary whitespace, smaller byte count, better for network transfer. The second is pretty-printed — indented, easier to read.
In production APIs, most servers send minified JSON. When debugging, you want the pretty version. The JSON Formatter tool does exactly this — paste in minified JSON and get back readable, indented output instantly.
Most languages have pretty-print support built in:
import json
print(json.dumps(data, indent=2))JSON.stringify(data, null, 2)Special Characters in Strings
Certain characters must be escaped inside JSON strings with a backslash:
| Character | Escaped form |
|---|---|
| Double quote | \" |
| Backslash | \\ |
| Newline | \n |
| Tab | \t |
| Carriage return | \r |
| Unicode | \uXXXX |
{
"message": "She said \"hello\"",
"path": "C:\\Users\\Alice\\Documents",
"multiline": "Line one\nLine two"
}Working with JSON in Practice
Once you've captured a JSON payload, you'll often want to transform it. Two common needs:
Converting to CSV for spreadsheet analysis — the JSON to CSV tool handles this without writing a script. It flattens nested objects and maps keys to columns.
Converting to YAML for config files — YAML is a superset of JSON and much more readable for human-edited config. The JSON to YAML converter does this losslessly for any standard JSON input.
For the full specification, the authoritative reference is json.org — it's remarkably concise.
If you're building or consuming APIs, you'll also want to understand how JSON fits into the broader REST design picture. Read REST API Design Best Practices for how JSON responses should be structured at the API level.
Wrapping Up
JSON's rules are strict by design. Internalize the six data types, the double-quote requirement, and the no-trailing-comma rule, and you'll rarely hit parse errors. When you do, paste the problematic JSON into the JSON Formatter — it highlights the exact line where things went wrong and formats the rest so you can read it clearly.