Working with JSON Effectively
JSON looks simple until it breaks. This guide covers the rules that trip people up, tools that help, and habits that keep your data clean.
Last updated July 23, 20265 min read
The rules JSON actually enforces
- Keys must be double-quoted strings — single quotes are invalid.
- No trailing commas after the last item in an array or object.
- No comments. Ever. If you need one, add a documentation field.
- Numbers cannot start with a leading zero or a plus sign.
- Only unicode strings, numbers, booleans, null, arrays, and objects are allowed as values.
Beautify vs minify
Beautified JSON is indented for humans — usually two spaces. Minified JSON strips all whitespace for the smallest payload over the wire.
Use minified in production APIs and beautified for logs, debugging, and configuration files kept in source control.
Common parse errors
- 'Unexpected token' — usually a trailing comma or an unclosed bracket.
- 'Unexpected end of JSON input' — the payload was cut off mid-transfer.
- 'Invalid character' — a smart quote or non-breaking space slipped in from a word processor.
Tip: When a payload will not parse, paste it into a formatter first. The error line number is nearly always accurate.
Handling large JSON files
Files over a few megabytes are painful in text editors. Use a streaming parser (ijson, JSONStream) rather than loading the whole document into memory.
For sharing, gzip a minified copy — the ratio is often 10:1 or better on repetitive structures.