Guide · Data formats
JSON Formatting, Validation and the Mistakes That Break Payloads
JSON looks forgiving. It is not. The specification allows no comments, no trailing commas and no single-quoted strings, and a parser stops at the first violation. Most JSON bugs an application sees in production come from one of six causes.
1. Trailing commas
JavaScript tolerates {"a":1,"b":2,}. JSON does not. The same applies to arrays. The fix is mechanical, but when the payload is generated by hand — in a config file, a template, or a test fixture — it happens constantly.
2. Single quotes
{"name": 'test'} // invalid
{"name": "test"} // valid
Only double quotes are legal for strings and keys. Strings pasted from Python source code or from shell scripts are the usual source of this error.
3. Duplicate keys
JSON does not define what happens when an object contains the same key twice. Most parsers silently keep the last value; some throw. Either way the document is ambiguous, and the behaviour can differ between your development language and the service you are calling. Treat duplicates as a bug even when nothing complains.
4. Number precision
JSON has one numeric type, and its interoperability range is generally taken to be the IEEE-754 double. Identifiers such as database keys, tweet IDs and order numbers often exceed 253 and lose their exact value when parsed into a double. Send large integers as strings and convert them at the edges of your system.
5. Invisible characters
Two culprits cause most “valid-looking but rejected” payloads:
- A UTF-8 byte order mark at the start of a file. It is invisible in an editor but is not legal at the start of a JSON document.
- Raw control characters inside strings — a literal newline or tab. These must be escaped as
\nand\t.
6. Wrong top-level structure
Many APIs require the top level to be an object rather than an array, and a surprising number of integration failures come down to an array being sent where an object was expected. Check the specification rather than inferring from an example.
Reading a parser error
A useful parser tells you the line, the column and sometimes a snippet. Read it precisely:
- Unexpected token } near the end of a block almost always means a trailing comma.
- Unexpected token ' means an unescaped quote inside a string, or a stray apostrophe.
- Unexpected end of input means an unclosed brace or bracket — count them.
Formatting: pretty versus compact
Pretty-printed JSON is for humans; compact JSON is for the wire. Whitespace is not significant in JSON, so minifying a payload before sending it saves bandwidth with no semantic change. Keep the readable version in version control and minify at the boundary.
A working habit
Validate before you debug. Paste the document into the JSON formatter on the home page, which runs entirely in your browser, and confirm it parses before you start looking for problems in your application code. When a payload contains credentials or customer data, use a client-side tool rather than an online service that uploads it.