JSON (JavaScript Object Notation) is the lingua franca of modern web development. Every API you call, every configuration file you edit, and every NoSQL database you query likely uses JSON. Yet even experienced developers waste hours debugging malformed JSON. This guide covers the rules, common pitfalls, and practical techniques for formatting and validating JSON correctly.
JSON Syntax Rules You Must Know
JSON has a small but strict set of rules. Violate any of them, and your parser will fail — often with an unhelpful error message.
- Keys must be strings — wrapped in double quotes. Single quotes are not valid JSON:
{"name": "Alice"}✓ vs{'name': 'Alice'}✗ - Strings must use double quotes — no single quotes, no template literals
- No trailing commas —
{"a": 1, "b": 2,}is invalid. Remove the comma after the last item - No comments — JSON does not support
//or/* */comments. JSONC (JSON with Comments) is a non-standard extension used by VS Code and TypeScript configs, but it's not valid JSON - Values can be: strings, numbers, objects, arrays, booleans (true/false), or null
- No undefined or NaN — these JavaScript values are not valid in JSON
The Most Common JSON Errors (and How to Fix Them)
1. Trailing Commas
This is the single most common JSON error. Most developers are used to JavaScript's permissive syntax, where trailing commas are fine. In strict JSON, they cause a parse error. The fix is simple: remove them.
2. Unquoted Keys or Single-Quoted Strings
Python developers often hit this because Python dicts accept both {name: "Alice"} and {'name': 'Alice'}. Neither is valid JSON. Always double-quote both keys and string values.
3. Control Characters in Strings
Raw newlines, tabs, and other control characters inside strings will break JSON parsing. Use \n, \t, and \r escape sequences instead. This often happens when JSON is generated from user input or log files that contain unescaped whitespace.
4. Incorrect Number Formats
JSON numbers must not have leading zeros (except for 0 itself), and they don't support hex (0xFF) or octal notation. Scientific notation is allowed: 2.5e10 is valid.
5. Unicode and Encoding Issues
JSON must be encoded in UTF-8. If your file contains BOM (Byte Order Mark) characters, some parsers will fail. Non-ASCII characters should be escaped as \uXXXX or included directly as UTF-8 text.
Formatting JSON for Readability
A minified 500KB API response is efficient for transmission but unreadable for debugging. Proper formatting (pretty-printing) adds indentation and line breaks to make the structure clear.
Example — Minified:
{"users":[{"id":1,"name":"Alice","email":"alice@example.com","roles":["admin","editor"]},{"id":2,"name":"Bob","email":"bob@example.com","roles":["viewer"]}]}
Example — Formatted (2-space indent):
{
"users": [
{
"id": 1,
"name": "Alice",
"email": "alice@example.com",
"roles": ["admin", "editor"]
},
{
"id": 2,
"name": "Bob",
"email": "bob@example.com",
"roles": ["viewer"]
}
]
}
Two-space indentation is the most common convention (used by most web formatters), though four spaces are standard in some ecosystems like Prettier with the "json" parser.
Working with Nested JSON
Real-world JSON is often deeply nested. When you're extracting a specific value, a path-based approach is more reliable than manual searching.
- JavaScript:
data.users[0].roles[1]→ "editor" - Python:
data["users"][0]["roles"][1] - jq (CLI):
cat data.json | jq '.users[0].roles[1]'
For complex queries (filtering, mapping, aggregation), jq is indispensable. It's the standard tool for JSON processing on the command line and supports conditions, string operations, and math.
Validating JSON in Your Workflow
Validation should happen at multiple stages:
- API responses: Use schema validation (JSON Schema) to verify structure, not just syntax
- Configuration files: Validate on application startup with clear error messages pointing to the problematic line
- User input: Never trust client-side validation alone — always validate server-side
- During development: Use a linter or formatter that catches errors before runtime
For quick validation and formatting without installing anything, Risetop's JSON formatter and validator processes your data directly in the browser. Paste your JSON, and it instantly tells you if it's valid — and if not, where the error is. No data is sent to any server.
JSON vs. Alternatives: When to Use What
- JSON: Best for APIs, configs, and general data exchange. Human-readable, widely supported
- YAML: Better for configuration files where readability matters (supports comments, anchors)
- MessagePack / CBOR: Better for high-performance or bandwidth-constrained scenarios (binary format)
- XML: Legacy systems, documents with mixed content, or when you need built-in schema validation (XSD)
Conclusion
JSON's simplicity is its strength, but that simplicity comes with strict rules. Knowing the common errors — trailing commas, unquoted keys, unescaped control characters — will save you significant debugging time. Whether you're consuming an API, writing a config file, or processing log data, proper formatting and validation aren't optional — they're essential for reliable software.