Comprehensive Guide to JSON¶

What It Is¶

JSON (JavaScript Object Notation) is a strict, minimal data-interchange format derived from JavaScript object literal syntax but language-independent in practice. It's the backbone of REST APIs, is natively parseable in essentially every programming language's standard library, and underlies or is accepted as an alternative form by many other formats (Kubernetes manifests accept JSON as well as YAML, for instance).

Its defining trait is strictness: there's exactly one way to write valid JSON for a given piece of data, no ambiguity, no optional syntax. That's precisely what makes it ideal for machine-to-machine communication, even though it's less pleasant to hand-write than YAML or TOML.

Spec: json.org and formally RFC 8259.

Core Syntax¶

{
  "name": "Andrew",
  "active": true,
  "count": 42,
  "ratio": 3.14,
  "nothing": null,
  "tools": ["terraform", "kubernetes", "elasticsearch"],
  "server": {
    "host": "localhost",
    "port": 8080,
    "tls": {
      "enabled": true
    }
  }
}

The complete grammar¶

JSON has exactly two structural types and four primitive types — that's the whole language:

Structures:
- Object — {}, an unordered collection of "key": value pairs, keys always double-quoted strings
- Array — [], an ordered list of values

Primitives:
- String — always double-quoted; supports escapes: \", \\, \/, \n, \t, \r, \b, \f, and \uXXXX for arbitrary Unicode code points
- Number — no distinction between integer and float in the grammar itself (42 and 42.0 are both just "number"); supports scientific notation (1.5e10); no support for NaN, Infinity, or hexadecimal
- Boolean — true or false (lowercase only, unquoted)
- null — lowercase, unquoted

There is no separate "date" type, no comments, and no trailing commas — all deliberate simplifications relative to YAML.

Strict Rules to Remember¶

• Double quotes only. Single quotes around strings or keys are invalid JSON, even though they're valid JavaScript object literal syntax.
• No comments, period. Not in the spec at all. Some tools support a .jsonc extension (JSON with Comments) as a deliberate non-standard extension — e.g., VS Code's settings.json — but a plain JSON parser will reject it.
• No trailing commas. ["a", "b",] is invalid, though a number of lenient parsers (and JavaScript's own object literals) will silently accept it — don't rely on that portability.
• Keys must be strings. {1: "a"} is invalid; it must be {"1": "a"}.
• Whitespace is cosmetic only — unlike YAML, indentation carries no structural meaning; JSON can be minified to a single line with no semantic change.
• Top-level value can be anything in modern JSON (a bare string, number, or array is valid at the root) — older, stricter readings of the spec required the root to be an object or array, but RFC 8259 relaxed this.

Gotchas¶

• No comments means no inline documentation in the file itself — a common practical complaint for hand-edited config, and part of why YAML and TOML exist as friendlier alternatives when humans are the primary authors.
• Large integers can silently lose precision. JSON numbers are commonly parsed into IEEE 754 double-precision floats by default in many languages (notably JavaScript itself), so 64-bit IDs or timestamps beyond about 2^53 can be corrupted on parse unless the library specifically supports big integers or you keep such values as strings.
• Duplicate keys are undefined behavior per spec. Most parsers just silently keep the last occurrence, but this isn't mandated — don't write JSON that relies on it.
• No native date/time type. Dates are just strings by convention — usually ISO 8601 ("2026-08-25T14:30:00Z") — with zero enforcement from the format itself; validation is entirely up to whatever's consuming the data.
• Escaping forward slashes (\/) is optional, which is why you'll see URLs in JSON both escaped and unescaped depending on the source library — both are valid.
• Encoding assumptions: JSON text is specified to be UTF-8, UTF-16, or UTF-32 — mixing encodings between producer and consumer is a classic source of mangled output, though UTF-8 is the de facto universal choice today.

Tools¶

• jq — the standard CLI for querying and transforming JSON, with its own small query language:
  bash cat file.json | jq '.server.port' jq -r '.tools[]' file.json # -r strips quotes from string output jq '.servers | map(.name)' file.json
• jsonlint.com — online validator, useful for quickly spotting a syntax error
• Native standard-library support in essentially every language — Python's json, Go's encoding/json, JavaScript's JSON.parse/JSON.stringify, Rust's serde_json — so there's rarely a reason to hand-roll a parser or reach for a third-party dependency just to read JSON
• JSON Schema — a JSON-based vocabulary for validating the structure/types of other JSON documents, widely used for API contract validation