What This Covers
Operational questions: how to minify and beautify, how to locate parse errors, how to turn a schema into a contract, how to handle large files, and how to diff two revisions. For JSON's types and grammar themselves, see the complete JSON guide.
Syntax Cheat Sheet: Only the Real Traps
Grammar details live in the other article; here is one comparison table. Every invalid form below is one you actually meet while debugging:
| Snippet | Verdict | Why |
|---|---|---|
{"a": 1} |
✅ | Valid |
{a: 1} |
❌ | Key not quoted |
{'a': 1} |
❌ | Single quotes |
{"a": 1,} |
❌ | Trailing comma |
{"a": 01} |
❌ | Leading zero |
{"a": NaN} |
❌ | No such literal in JSON |
{"a": undefined} |
❌ | No such type |
[1, "2", null] |
✅ | Arrays may mix types |
One trap outside the table, common with non-English content: a leading BOM (\uFEFF) makes JSON.parse fail at position 0 while the editor shows nothing unusual.
Formatting vs Minifying: Two Different Jobs
Stripping all indentation and newlines typically cuts 30–50% of the payload; where key names repeat heavily, gzip or Brotli widens the gap further. Minify production responses, message bodies and configs; beautify for reading, review and debugging.
Never strip whitespace with a regex—it eats spaces inside string values too. Use a formatter's minify mode, which preserves semantics.
Indentation style has no correct answer: 2 spaces is the JS/TS default (Prettier, ESLint), 4 spaces is common in Python and Java projects. What matters is consistency within a repository; inconsistency hurts more than the choice.
Two counter-intuitive points:
- Formatting before signing always breaks verification. HMAC, digital signatures and JWTs are computed over the raw byte sequence; one extra space changes the result completely.
- Do not print beautified large objects into production logs. Log the minified form and truncate by length, or write latency and log quota both run away.
Validation: Five Errors and How to Locate Them
JSON.parse usually throws nothing more than Unexpected token } in JSON at position 1234, which looks information-free. The distribution is actually fixed:
| Error type | Typical message | Actual cause |
|---|---|---|
| Trailing comma | Unexpected token } |
Extra comma after the last item |
| Single quotes | Unexpected token ' |
Copied from a JS literal |
| Unclosed bracket | Unexpected end of JSON input |
Missing } or ], reported at end of file |
| Comments | Unexpected token / |
Someone wrote a // note |
| BOM | Unexpected token at position 0 |
File starts with |
The locating rule is one sentence: read backwards from the reported position. A parser only throws at the character it cannot continue from, so the typo is usually a few lines earlier. By symptom:
- Reported at the end → almost certainly an unclosed bracket; count pairs from the outside in.
- Pointing at a comma → usually an extra trailing comma, not missing content.
- At position 0 → check BOM and encoding first.
- Mid-file → inspect the end of the previous line.
For what position really means (prefixes shifting it, and the 0-based index versus 1-based editor column), see JSON.parse errors explained. The fastest routine step remains pasting the raw content into a JSON formatter, where most implementations mark the line and column.
JSON Schema: A Contract, Not Documentation
Checking "is this legal JSON" settles syntax only; checking "are the fields and types right" needs a schema:
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"required": ["id", "email", "createdAt"],
"additionalProperties": false,
"properties": {
"id": { "type": "string", "format": "uuid" },
"email": { "type": "string", "format": "email" },
"age": { "type": "integer", "minimum": 0, "maximum": 150 },
"status": { "enum": ["active", "suspended", "deleted"] },
"createdAt": { "type": "string", "format": "date-time" }
}
}
A generated schema is loose inference; making it a contract takes three manual moves: put every genuinely mandatory field into required; add domain constraints (enum, format, minimum, minItems); tighten additionalProperties so undeclared fields fail outright.
Hand-written schemas drift from real data. A sturdier start is generating a draft from a real response (JSON Schema generator) and tightening item by item. Run it in CI with ajv and structural breakage from an API change surfaces before merge instead of as a 500 in production.
Large Files: Memory Is 3–10x the Text
The most commonly misjudged point: parsed JSON usually occupies 3–10x the original text in memory. Every key and value becomes a separate object or string with pointer and metadata overhead, so a 100MB file can need 500MB–1GB for a naive JSON.parse.
| File size | Recommended approach |
|---|---|
| < 10 MB | Just JSON.parse; no optimisation needed |
| 10–100 MB | Stream it, or process in batches |
| > 100 MB | Streaming mandatory; consider newline-delimited JSONL |
| > 1 GB | Switch to a columnar or binary format (Parquet, Arrow) |
| Library | Language | Notes |
|---|---|---|
simdjson |
C++ with bindings | SIMD-accelerated; GB/s-class parsing |
ijson |
Python | Lazy iteration, emits as it reads |
JSONStream |
Node.js | Incremental extraction by JSONPath |
serde_json StreamDeserializer |
Rust | Zero-copy friendly |
When you need only a few fields from a huge file, do not parse the whole tree: target them with a JSONPath expression and discard irrelevant branches as you read. Tune the expression against real data in the JSONPath finder before committing it to code.
Comparing Structures: What Actually Changed
After a config change or API upgrade, eyeballing two documents almost always misses something. Compare the parsed structure, not text lines:
- Added or removed keys → check
requiredand compatibility. - Changed values → check for type drift (
"1"versus1). - Reordered arrays → decide whether order carries business meaning.
JSON Diff reports structural differences and is far more reliable than a textual diff, which drowns in indentation and newline noise.
Security: Four Real Risks When Parsing JSON
| Risk | Impact | Fix |
|---|---|---|
Parsing with eval() / new Function() |
Remote code execution, total compromise | Always use JSON.parse |
| Prototype pollution | Deep-merge mutates every object's prototype | Strip __proto__/constructor/prototype before merging |
| Deep nesting stack overflow | Recursive parser crashes; denial of service | Enforce a depth limit before parsing |
| Large-integer precision loss | Money and order ids silently become wrong | Transmit fields above 2^53-1 as strings |
Number two is the sneakiest: JSON.parse('{"__proto__":{"isAdmin":true}}') returns an ordinary object where __proto__ is just a normal key, harmless on its own. The danger starts at deep merge:
const payload = JSON.parse('{"__proto__":{"isAdmin":true}}');
const config = {};
merge(config, payload); // Dangerous: pollutes Object.prototype
console.log({}.isAdmin); // true — every object in the app is affected
Number four is the most damaging in finance and ordering: 9007199254740993 parses to 9007199254740992, and nothing throws.
Task Cheat Sheet
| Task | Approach | Tool |
|---|---|---|
| Read a one-line minified JSON | Beautify with 2-space indent | JSON formatter |
| Track down a parse error | Paste it in and read the line/column | JSON formatter |
| Shrink a payload | Strip whitespace | JSON minifier |
| Browse a deep structure | Tree viewer | JSON viewer |
| Diff two config revisions | Structural diff | JSON Diff |
| Infer a schema from a response | Generate, then tighten | JSON Schema generator |
| Pull fields from a big file | JSONPath expression | JSONPath finder |
| Debug a field regex | Validate the pattern first | Regex tester |
Reproducible Results
The formatter's validation is not decoration: paste invalid inputs into the JSON formatter and the error pins the exact line and column—the same position Python's json.loads reports, because both follow one JSON spec.
Suggested workflow: paste → read the error → fix → format → minify. The last step doubles as proof that structure survived: diff the minified and pretty versions with the JSON diff tool — an empty diff means only formatting changed.