Reading Broken JSON: Formatting and Validation Basics
The most common JSON syntax errors, and how a formatter helps you find them fast.
JSON is deliberately tiny — six value types and almost no syntax. Nearly every error you hit comes from that minimalism, or from a producer that quietly added something JSON never supported.
The whole specification, briefly
| Type | Notes |
|---|---|
| Object | Unordered key/value pairs; keys must be double-quoted strings |
| Array | Ordered values; trailing commas are invalid |
| String | Double quotes only; escape backslash, quote and control characters |
| Number | No leading +, no leading zeros, no NaN or Infinity, no hex |
| Boolean | Lowercase true and false only |
| Null | Lowercase null; there is no undefined |
The errors that account for most failures
- Trailing comma after the last element — valid in JavaScript, invalid in JSON.
- Single quotes around strings or unquoted keys — a JavaScript object literal, not JSON.
- Unescaped characters inside strings, especially raw newlines and stray backslashes in Windows paths.
- A BOM or stray whitespace before the opening brace, which many parsers reject with a confusing message.
- NaN or Infinity emitted by a numeric serialiser — not representable in JSON.
- Duplicate keys — technically allowed by the grammar, but the last value silently wins in most parsers.
Formatting for humans and for machines
Pretty-printing with two-space indentation is for reading and diffing; minified JSON is for transport. Both parse identically, so choose by audience. For version control, formatting with stable key ordering makes diffs dramatically easier to review.
compact: {"id":7,"tags":["a","b"]}
pretty: {
"id": 7,
"tags": ["a", "b"]
}Validating structure, not just syntax
A file can be perfectly valid JSON and still be wrong for your application. JSON Schema describes required fields, types, ranges and enumerated values, which turns a runtime crash into a clear validation message at the boundary.
- Validate incoming payloads at the API edge, before business logic.
- Reject unknown fields when the contract is strict; ignore them when forward compatibility matters more.
- Version the schema alongside the endpoint so old clients keep working.
Streaming and very large files
Parsing a multi-gigabyte JSON array into memory will fail. NDJSON — one JSON object per line — is the usual answer for logs and exports, because each line parses independently and the file can be processed as a stream.
Use the JSON formatter to pretty-print and validate, the JSON to CSV converter for spreadsheets, and the JSON escape tool when embedding JSON inside another string.
Frequently asked questions
Can JSON have comments?
Not in the standard. Use a dedicated description field, or a superset like JSONC if your tooling supports it — but never send comments to a strict parser.
How do I represent a date?
There is no date type. The convention is an ISO 8601 string such as 2026-03-14T09:30:00Z, which sorts correctly as text and parses everywhere.
Is JSON or YAML better for configuration?
YAML is friendlier to write and supports comments; JSON is unambiguous and parses faster. Many teams author YAML and convert to JSON for machine consumption.
Why does my API reject valid-looking JSON?
Check the Content-Type header, a UTF-8 BOM at the start of the file, and trailing commas. Those three cause most rejections that look inexplicable.