What This Covers
The language itself: which types exist, why the grammar is strict, and where values silently distort. Formatting, validation, schema work, large files and structural diffing are operations, covered in the JSON formatter and validator guide.
Six Types, No Seventh
| Type | Example | Key point |
|---|---|---|
| String | "oltool" |
Double quotes only; supports \n, \t, \uXXXX escapes |
| Number | 42, 3.14, -0.5 |
No integer/float split; always a double |
| Boolean | true / false |
Lowercase, not a string |
| Null | null |
"Present but empty", distinct from "key absent" |
| Object | {"k": "v"} |
Unordered pairs; keys must be strings |
| Array | [1, 2, 3] |
Ordered list; element types may mix |
{
"user": {
"id": "u_1001",
"name": "denni",
"active": true,
"roles": ["admin", "editor"],
"metadata": null
},
"score": 98.5
}
null and "key absent" mean different things: {"a": null} versus {} parse as null versus missing in most languages, and that distinction carries "clear this field" versus "leave it unchanged" in business logic.
Nesting: Two Rules Cover Any Structure
An object is one record's attributes, an array is a set of homogeneous elements, and an array of objects is a table—the most common API response shape. No matter how deep it gets, the grammar adds no new rules, which is why every language implements JSON cheaply.
The cost is legibility: once nesting gets deep, counting braces by eye fails. Expand minified text first with a JSON formatter, and switch to a JSON tree viewer when you need to collapse levels.
Where the Grammar Is Strict
Strictness is not fussiness. JSON is a cross-system format, and parsers refuse to infer—if ambiguity were tolerated, the same string could parse differently in different languages. These forms always fail in a standard parser:
- Single-quoted keys or values, or bare key names: double quotes are mandatory.
- A comma after the last element: trailing commas are illegal.
- A raw newline or tab inside a string: it must be
\n/\t. //comments,NaN,Infinity, leading zeros: all illegal.
Conversely, the top level need not be an object: [], "x" and 42 are valid JSON. Many "parses fine but every field is null" bugs come from treating a top-level array as an object.
Such code often runs in a browser console because that evaluates a JavaScript expression—similar syntax, different rulebook. That is the most common source of "works locally, fails in production".
Precision: JSON Has No Integers
RFC 8259 defines one numeric type, number, without prescribing representation; implementations map it to the IEEE 754 double. A double has 52 mantissa bits, so the largest exactly representable consecutive integer is 2^53-1—beyond that you only get an approximation, and no error is raised.
The victims are fields that look like IDs and never get arithmetic: 18-digit order numbers, 64-bit snowflake IDs, national ID numbers, and money carried as decimals. To check: Number.MAX_SAFE_INTEGER prints 9007199254740991, and JSON.parse('{"id":9007199254740993}') yields an id of 9007199254740992.
Keep such numbers as strings in transit: serialize as "id": "9007199254740993" and compare or display them as strings. Note that JSON.parse's reviver cannot repair this—the value it receives is already a rounded Number; preserving precision requires a parser that treats large integers as strings.
Serialization Fails More Quietly Than Parsing
Parsing errors at least throw; serialization silently rewrites data. JSON.stringify drops functions, undefined and Symbols outright, and throws TypeError on circular references. When whole frontend state is cached as JSON and comes back with fewer fields, this is usually why.
Check by comparing key sets before and after; to fail loudly at the exact spot, use a replacer:
JSON.stringify(state, (k, v) => {
if (v === undefined) throw new Error(`undefined at ${k}`)
return v
})
Injection presupposes treating untrusted input as part of the grammar: building JSON by string concatenation lets a quote in user input close a field early, while eval / new Function on unknown text executes the other party's string as code. Emit only through JSON.stringify, consume only through JSON.parse, and validate the resulting structure.
Choosing a Format: The Decision Only
| Dimension | JSON | XML | YAML | MessagePack |
|---|---|---|---|---|
| Readability | Good | Fair | Best | Poor (binary) |
| Parse speed | Fast | Slow | Slow | Fastest |
| Comments | No | Yes | Yes | No |
| Size | Medium | Large | Medium | Smallest |
| Typical use | API / storage | Legacy / SOAP | Human config | High-perf transport |
Decision order: downstream accepts text only and calls are frequent → JSON; humans edit daily and need comments → YAML for deep hierarchies, TOML for shallow ones; bandwidth or latency is the bottleneck → a binary format such as MessagePack, with JSON semantics underneath. Choose XML only when a legacy system forces it.
Reproducible Results
Two classic distortions, one line of Python each, independent of language:
# Trap 1: integers above 2^53 lose precision through floats
print(2 ** 53 + 1) # → 9007199254740993
print(int(float(2 ** 53 + 1))) # → 9007199254740992 (off by one!)
# Trap 2: duplicate keys do not raise; the last one wins
import json
print(json.loads('{"a": 1, "a": 2}')) # → {'a': 2}
The first is why an order number's last three digits turn into zeros: a float cannot hold an 18-digit integer. The second is worse—{"a": 1, "a": 2} raises nothing in Python or JS, the last value just wins, and after a config merge you cannot tell a layer went missing. To confirm a rewrite changed only formatting, diff both versions in the JSON formatter.