Six data types.
A handful of rules.
Used everywhere.

02 · The whole grammar

🧱 Syntax rules & data types

A JSON document is exactly one value. Usually that value is an object or an array, but a bare string, number, or true is also valid JSON. Values come in six types:

That's it. There is no date type, no comment syntax, no binary type and no way to reference another part of the document. Everything else — dates, money, IDs, images — is a convention layered on top of those six types.

🌐 A few rules people forget

• Whitespace is insignificant between tokens, so minified and pretty-printed JSON are the same data.
• Encoding is UTF-8 for JSON exchanged between systems (RFC 8259 requires it). The media type is application/json.
• Duplicate keys aren't forbidden by the grammar, but the spec says names should be unique, and parsers disagree about what to do with them — most keep the last one. Don't rely on either behaviour.
• Key order isn't meaningful. Most parsers preserve it, but a consumer is allowed to ignore it.

03 · Read a real one

🔍 A realistic example

Here's the kind of payload an order API might return. It uses every one of the six types:

{
  "orderId": "ORD-10482",
  "createdAt": "2026-03-14T09:30:00Z",
  "paid": true,
  "couponCode": null,
  "customer": {
    "name": "Asha Verma",
    "city": "Pune"
  },
  "items": [
    { "sku": "TEA-250", "qty": 2, "price": 249.00 },
    { "sku": "MUG-01",  "qty": 1, "price": 399.00 }
  ],
  "tags": ["gift", "express"]
}

Read it top-down: the document is one object; customer is a nested object; items is an array of objects; couponCode is present but explicitly empty. That last distinction matters — a key set to null and a missing key are different things, and many APIs use them to mean "cleared" versus "not sent".

Pasted a minified blob and can't see the structure? Drop it into the JSON Formatter to pretty-print, validate and explore it as a collapsible tree.

04 · Why it won't parse

🧯 The errors everyone hits

Most "invalid JSON" errors come from writing JavaScript object syntax — which is looser — and expecting JSON to accept it. These five cover the large majority of failures:

🕵️ Sneakier ones

• Smart quotes. Copying JSON out of a word processor or chat app can turn " into curly quotes, which look right and fail to parse.
• A byte-order mark at the start of a file saved by some Windows editors. Many parsers reject it.
• Unescaped control characters — a literal tab or newline inside a string must be written as \t or \n.
• Python's output. json.dumps(float("nan")) writes NaN by default, which other parsers reject. Pass allow_nan=False to catch it at the source.
• Printing a dict instead of serialising it. str(my_dict) in Python gives single quotes and True/None — it looks like JSON but isn't.

05 · Picking a format

⚖️ JSON vs XML vs YAML

All three represent nested, structured data. They differ in what they optimise for.

XML still wins for document-style data and established standards — our What is XML? guide covers where and why.

06 · In your code

🛠️ Parsing & generating JSON

Every language has the same two operations: parse (text → objects) and serialise (objects → text). Always use the built-in library — never build JSON by concatenating strings, because escaping is where hand-rolled JSON breaks.

// text → object (throws SyntaxError on invalid input)
const order = JSON.parse(text);

// object → text; the third argument pretty-prints with 2 spaces
const body = JSON.stringify(order, null, 2);

// fetch() does the parse for you
const res = await fetch("/api/orders/10482");
const data = await res.json();

using System.Text.Json;

public record Item(string Sku, int Qty, decimal Price);
public record Order(string OrderId, bool Paid, List<Item> Items);

// Web defaults: camelCase names, case-insensitive matching
var options = new JsonSerializerOptions(JsonSerializerDefaults.Web);

Order? order = JsonSerializer.Deserialize<Order>(json, options);
string text  = JsonSerializer.Serialize(order, options);

import json

order = json.loads(text)                        # str → dict
text  = json.dumps(order, indent=2, allow_nan=False)

with open("order.json", encoding="utf-8") as f:
    order = json.load(f)                        # file → dict

07 · Contracts

📐 JSON Schema, briefly

Valid JSON only means "it parses". Whether it has the right shape — required fields present, numbers positive, strings matching a pattern — is a separate question. JSON Schema is the standard way to write that shape down, itself as JSON:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["orderId", "items"],
  "properties": {
    "orderId": { "type": "string", "pattern": "^ORD-[0-9]+$" },
    "paid":    { "type": "boolean" },
    "items": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "object",
        "required": ["sku", "qty"],
        "properties": { "qty": { "type": "integer", "minimum": 1 } }
      }
    }
  }
}

You'll meet JSON Schema without looking for it: OpenAPI uses it to describe request and response bodies, editors use it for autocomplete in config files, and validator libraries exist for every major language. It's worth writing one for any payload that crosses a team boundary.

08 · Quick answers

💬 Common questions