JSON Guide

JSON, from the grammar up

JSON — JavaScript Object Notation — is a text format for structured data. It carries the payload of most REST and GraphQL APIs, nearly every modern configuration file, and the output of most structured loggers. If you write software that talks to anything else, you read and write JSON.

Its whole grammar fits on one page at json.org, which is unusual and deliberate. Douglas Crockford specified JSON in the early 2000s by taking a subset of JavaScript's object literal syntax and removing everything that was not needed to describe data. It is standardised twice, in parallel: as RFC 8259 by the IETF and as ECMA-404 by Ecma International.

This guide is the hub for that topic. Each section below summarises one area and links to a full treatment.

The six types

JSON has exactly six types, and no way to define more. Four are primitive:

• string — double-quoted Unicode text: "Ada Lovelace"
• number — a decimal, no distinction between integer and float: 42, 3.14, -1.5e3
• boolean — lowercase true or false
• null — lowercase null

Two are structured:

• object — an unordered set of key/value pairs: {"id": 42, "active": true}
• array — an ordered list of values: [1, 2, 3]

That is the entire type system. There is no date type, no integer/float distinction, no binary type, no comment, no reference or pointer. Dates are conventionally carried as ISO 8601 strings ("2026-07-29T10:45:00Z"); binary data as Base64 strings.

{
  "id": 42,
  "name": "Ada Lovelace",
  "active": true,
  "score": 99.5,
  "manager": null,
  "roles": ["admin", "engineer"],
  "address": {
    "city": "London",
    "postcode": "SW1A 1AA"
  }
}

Objects and arrays nest to any depth, which is what makes JSON able to describe arbitrary structures with such a small grammar.

Where to go next

JSON Syntax Rules — the complete rules for strings, numbers, objects, and arrays, and the specific ways JSON is stricter than JavaScript. Read this if JSON keeps failing to parse for reasons that are not obvious.

JSON Formatting — what pretty-printing actually does, why 2-space and 4-space conventions differ by ecosystem, and how formatting works in JavaScript, Python, and jq.

Common JSON Errors — every parse error you are likely to see, what actually causes it, and the fix. Start here when something is broken right now.

JSON Validation — the difference between syntax validation and schema validation, and when you need JSON Schema.

Minifying JSON — what minification saves, and the reason it is usually not worth doing on API responses.

JSON vs XML vs YAML — an honest comparison, including the cases where JSON is the wrong choice.

JSON Best Practices — naming conventions, structuring API responses, handling dates and money, and the mistakes that are expensive to reverse later.

Choosing a tool rather than learning the format? See our honest comparisons of the major JSON formatters — including JSONLint, CodeBeautify, and browser extensions — each of which names what the alternative does better.

Why JSON won

XML dominated data interchange through the early 2000s. JSON displaced it for most web use because of a few concrete advantages:

• Less overhead. No closing tags, no namespaces, no schema declaration required.
• A direct mapping to native types. A JSON object parses to a dictionary or hash map in essentially every language; an XML document parses to a tree you must then walk.
• A parser is already there. Browsers ship JSON.parse; no library needed.
• A grammar you can hold in your head. Six types and a page of rules.

The trade-off is that JSON carries no built-in schema, no comments, no namespaces, and no attribute/element distinction. For document markup — where text and structure are interleaved — XML remains the better tool. See JSON vs XML vs YAML for the full comparison.

The parts that surprise people

A few behaviours catch out even experienced developers, and all of them follow from the type system above.

Numbers are doubles. RFC 8259 does not mandate a precision, but in practice parsers use IEEE 754 double-precision floats. Integers above 2^53 lose precision — a real problem for 64-bit database IDs and Twitter/X-style snowflake identifiers. The standard fix is to transport large integers as strings.

Key order is not meaningful. An object is defined as an unordered set of pairs. Most parsers preserve insertion order in practice, but nothing in the specification requires it, so never rely on it.

Duplicate keys are undefined behaviour. {"a": 1, "a": 2} is not forbidden by the grammar, but the spec does not say which value wins. Most parsers keep the last. Do not produce them.

There is no date type. Every date in JSON is a string or a number by convention, not by specification.

Any value can be the top level. Under RFC 8259, 42, "hello", and true are all complete, valid JSON documents. The older RFC 4627 required an object or array at the root; that restriction was lifted.

Reference

• json.org — Crockford's canonical grammar, on one page
• RFC 8259 — the current IETF Internet Standard
• ECMA-404 — the parallel syntax standard
• MDN: Working with JSON — a practical introduction
• JSON Schema — for validating structure, not just syntax