JSON Validation Mistakes That Break Production
Most JSON bugs that reach production are not syntax errors. A syntax error gets caught by the parser in the first ten seconds. The expensive ones are payloads that parse cleanly and then do the wrong thing — silently, with no stack trace and no log line.
These are the ten that keep showing up, in roughly the order they cost money.
1. Duplicate keys never raise an error
RFC 8259 says object names SHOULD be unique. Not MUST. Every mainstream parser resolves a duplicate by keeping the last value and discarding the earlier one, and none of them complain.
The classic failure is a config merge: your defaults are serialised first, the environment override second, and both are concatenated into one string instead of merged in memory. The override wins — until someone edits the file with a tool that reorders keys, and the default silently takes over. Feature flag off, cache TTL back to 60 seconds, nothing in the logs.
Detect it by scanning the raw text before parsing. After JSON.parse the information is gone.
2. Integers above 2^53
JavaScript numbers are float64. 9007199254740993 comes out as 9007199254740992. Order IDs, snowflake IDs and 20-digit account numbers all sit above that line. The corruption happens on the client, before the request is sent, so no server-side validation can catch it: you send a well-formed request for an ID that belongs to nobody.
Keep identifiers as strings in the contract. If you must accept numbers, use a parser that preserves big integers, and never round-trip an ID through a JS object.
3. Trailing commas, comments and single quotes
You edit a config, add a comment to explain a value, and the file becomes JSON5 rather than JSON. PHP makes this worse than most languages: json_decode() returns null on failure and only fills json_last_error(). Code that does $data = json_decode($body, true) and then reads $data['items'] gets a warning about null and carries on with an empty set.
The same trap exists for the literal null: a valid payload of null and a broken payload both return null. Check the error, not the return value.
4. Byte-order marks and non-UTF-8 input
A BOM is three bytes, EF BB BF, at the start of the file. Excel, Notepad and a dozen export buttons add it. Then JSON.parse throws "Unexpected token" pointing at line 1, column 1, where nothing looks wrong at all. Python's json.loads raises an equally unhelpful message.
Strip the BOM on ingest and reject bodies that are not valid UTF-8 before parsing. A single Latin-1 byte from a customer name pasted out of a legacy system will otherwise cost an hour to find.
5. Numbers that are not JSON numbers
NaN, Infinity, +1, .5, 0x1F, 1_000 and 0123 are all legal in JavaScript source and all invalid in JSON. They usually arrive from a serialiser that was handed a float it did not sanitise. Fix the producer, not the consumer — a validator on the receiving side only tells you which request died.
6. Syntax-valid is not schema-valid
This is the distinction that matters most. A JSON validator answers "do these bytes parse". It does not answer "is price a number, is items an array, is email present".
The bug that bites hardest is the string-number: one integration sends "price": "19.90", another sends 19.9. Your total becomes 19.9019.9 from concatenation, or NaN from arithmetic. Both render as an empty cell in the UI — exactly the class of bug reported as "the invoice page is broken" with no error message.
Validate in two stages: syntax first, because it gives you the exact line and column; then shape, with a schema or typed decoding, because that catches the wrong types.
7. Dates are strings, so anything goes
JSON has no date type, and every team invents its own convention. In one week of API logs you can find "2026-11-14", "2026-11-14T08:00:00Z", "2026-11-14T08:00:00+03:00", "14/11/2026" and 1763107200. The first and the last are indistinguishable from a date at a glance and off by hours once parsed.
Pick ISO 8601 with an explicit offset, always. Never local time without an offset — a payload written at 08:00 in Riga and read as 08:00 in Berlin is a real two-hour bug, not a rounding issue.
8. Empty string, null and missing are three different values
In a PATCH payload, {"name": null} means clear the field, {"name": ""} means set it to empty, and {} means leave it alone. If your validator coerces null to "" for convenience, you have just deleted a customer's data on a request that was supposed to change their email.
Model the three states explicitly: required is about presence, nullable is about the value. Conflating them is how "why did the phone number disappear" tickets get born.
9. Escaping: lone surrogates and literal newlines
"\ud800" is syntactically valid JSON but not a valid UTF-16 sequence. Some parsers accept it and then fail when you serialise to UTF-8, which turns bad input into a 500 on the way out. Literal newlines inside a string are also invalid: they must be \n.
The common production source is truncation. Cut a name at 150 characters with substring() and you can split an emoji surrogate pair in half, producing a string that no longer encodes. Truncate by code point, not by UTF-16 unit or byte.
10. Parsing responses you never checked
Status and content type come first, JSON second. When a proxy returns a 502 HTML page, or a WAF blocks a 2 MB body, your client calls JSON.parse on HTML and logs Unexpected token <. The message is technically correct and completely misleading.
Check res.ok and the content type, then parse. Also test the shape that changes with row count: XML-to-JSON converters return {"item": {"id": 1}} for one row and {"item": [{"id": 1}, {"id": 2}]} for two. That inconsistency ships in more APIs than anyone admits.
A short checklist
- Scan for duplicate keys in the raw text before parsing.
- Keep IDs as strings; never round-trip them through a float.
- Check the parse error, not just the return value.
- Strip the BOM; reject non-UTF-8 bodies.
- Validate syntax, then validate shape.
- ISO 8601 with an offset, no exceptions.
- Model null, empty and missing separately.
- Check status and content type before parsing.
When a payload fails, get the exact position instead of the parser's guess: paste it into the JSON Validator and it reports the line and column of the first real error. Once it parses, JSON Formatter pretty-prints and sorts the structure so duplicate keys and mixed types become visible to the eye. For reviewing a large config in a diff, convert it with JSON to YAML — YAML indentation makes nesting errors obvious. And if the payload is really tabular data that should never have been nested, JSON to CSV flattens it into something a spreadsheet can argue with.
None of these checks are exotic. They are the difference between a parser that says "ok" and a system that is actually correct.