If you have been writing any kind of web application, REST API, or configuration file in the last decade, you have almost certainly encountered JSON. It stands for JavaScript Object Notation and it has become the dominant format for transmitting structured data on the internet — yet many developers use it daily without fully understanding why it won out over the alternatives, or what its actual rules and limitations are.
A Brief History
JSON was formalized by Douglas Crockford in the early 2000s, though it was really just a subset of JavaScript's object and array literal syntax that had existed since the language's creation. The key insight was that a human-readable, lightweight text format was far more practical for REST APIs than the XML-heavy SOAP alternatives that dominated enterprise software at the time. JSON's minimalism was a feature: no namespaces, no schemas required, no verbose closing tags.
By the time ECMA-404 standardized it in 2013, JSON had already effectively won. Today it is used everywhere from public REST APIs and browser storage to Docker configurations and editor settings files.
The Syntax Rules
JSON has exactly six value types:
- String — must be wrapped in double quotes. Single quotes are not valid JSON.
"hello world" - Number — integers or decimals, no leading zeros (except
0.x), no NaN, no Infinity.42,3.14,-7 - Boolean — lowercase only:
trueorfalse - Null — lowercase only:
null - Array — an ordered list wrapped in square brackets:
[1, "two", true] - Object — a set of key-value pairs wrapped in curly braces, where every key must be a double-quoted string:
{"name": "Alice", "age": 30}
There are no comments in JSON — this is one of the most common frustrations for developers coming from configuration files. If you need a JSON-like format with comments, look at JSONC (JSON with Comments), which is what VS Code's settings.json uses.
Trailing commas are also invalid JSON. {"a": 1,} will fail strict parsers, even though most JavaScript engines are lenient about it. When using a JSON validator, these two mistakes — missing or extra commas and the use of single quotes — account for the vast majority of syntax errors.
JSON vs XML vs YAML
Before JSON's rise, XML was the dominant data interchange format, especially in enterprise settings. XML is verbose but extremely expressive: it supports attributes, namespaces, schema validation via XSD, and mixed content (text and elements interleaved). JSON wins on compactness and parse speed for most web use cases, but XML remains relevant in document-centric contexts like SOAP, RSS, SVG, and Office formats.
YAML (YAML Ain't Markup Language) is JSON's superset in one sense — every valid JSON document is valid YAML. YAML supports comments, multi-line strings, and a human-friendlier syntax with significant whitespace. It is common in configuration files (Docker Compose, GitHub Actions, Kubernetes manifests) but its whitespace sensitivity has caused enough accidental bugs that many teams prefer JSON or TOML for configuration.
Common Mistakes and Gotchas
Date handling: JSON has no native Date type. Dates are usually encoded as ISO 8601 strings ("2026-05-12T10:00:00Z") or as UNIX timestamps (integers). Neither approach is universally agreed upon, so always document what format your API uses.
Number precision: JSON numbers are conceptually double-precision floats. If you need to pass 64-bit integers (like database primary keys), values above 2^53 will lose precision when parsed by JavaScript. The common workaround is to serialize large integers as strings.
Key ordering: JSON objects are technically unordered sets of key-value pairs. Most parsers preserve insertion order as a courtesy, but you should not rely on this for correctness.
Deeply nested structures: Some JSON parsers have recursion limits. Structures nested beyond a few hundred levels can cause stack overflows. This is rarely a problem in practice but worth knowing if you process untrusted input.
Best Practices
- Always validate JSON before passing it to downstream systems. A validator catches syntax errors instantly that would otherwise surface as confusing runtime exceptions.
- Use a stable, documented naming convention for keys — camelCase is conventional in JavaScript APIs, snake_case in Python.
- When designing APIs, be explicit about null vs. absent keys — they carry different semantic meaning.
- For large payloads, consider NDJSON (newline-delimited JSON) for streaming or CBOR for binary-compact serialization.
A good JSON formatter will catch syntax errors immediately, show you the structure visually, and let you minify or beautify on demand — which is why having one in your browser bookmark bar is one of the highest-value-per-effort developer habits you can develop.