The Whole Grammar in One Page

Every answer this book has shown you arrived in the same costume: braces, brackets, quotes, colons. That costume is JSON — JavaScript Object Notation, though nobody spells it out — and it looks like code, which is exactly the misunderstanding this page removes. JSON is not code. It is data written down: facts in text form, with strict rules about the punctuation. Nothing in it runs, loops, or decides.

Here is the claim that makes this chapter short: JSON's entire grammar is six kinds of value. Learn them on this page and there is no JSON anywhere — Tandem's, your bank's, any API on earth — that you cannot read. Think of a structured luggage tag: name, office, bags: 2. The tag describes; it never acts. JSON is luggage tags for data, nestable.

{
  "id": "st_014",
  "name": "Old Market",
  "capacity": 24,
  "free_bikes": 9,
  "status": "active",
  "location": {"lat": 47.21, "lon": 8.55}
}

Objects: Labelled Facts

Curly braces { } hold an object: a set of facts, each with a label. Inside, every entry is a pair — a name in double quotes, a colon, a value: "capacity": 24. The station specimen is one object: facts about one station. Order does not matter in an object; you find things by label, not by position, exactly like reading a form.

Arrays: Ordered Lists

Square brackets [ ] hold an array: values in order, without labels. When you fetched /v1/stations in Chapter 3, the fifty stations arrived as an array of objects — a list of luggage tags. In an array, position is the only address: first, second, third. Objects answer "what is this thing's capacity?"; arrays answer "what is the third one?"

The Four Leaf Values

Everything else in JSON is one of four simple values. Strings — text in double quotes: "Old Market". Numbers — bare digits: 24, 47.21. Booleans — the two bare words true and false. And null — a bare word meaning "deliberately nothing." That is the complete inventory: objects and arrays to give structure, four kinds of leaf to carry the facts. There is no fifth thing waiting in an advanced chapter. This is all of JSON.

Zero, Null, and Missing Are Three Different Answers

One distinction earns its own section because it bites in real data. "free_bikes": 0 says: counted, and there are none — an empty station. "free_bikes": null says: this field exists but deliberately holds nothing — perhaps the station is offline and the count is unknown. And no free_bikes key at all says: this response simply does not carry that fact. Three different statements. A report that treats them as the same will lie to the city about which stations are empty versus which are unreported — the kind of quiet error the Thursday report cannot afford.