JSON Fundamentals

The format

{
  "id": 42,
  "name": "Ada",
  "active": true,
  "manager": null,
  "roles": ["admin", "editor"],
  "address": { "city": "Oslo", "zip": "0150" },
  "createdAt": "2025-03-14T09:30:00Z"
}

There are six value types: object ({} with key/value pairs), array ([]), string, number, boolean (true, false) and null.

Strict rules that trip people up

• Strings and keys use double quotes only.
• There are no comments and no trailing commas.
• There is no undefined, NaN, Infinity or date type: represent these as something else.
• Text is UTF-8, and characters such as " and \ inside strings must be escaped.
• Keys inside one object should be unique, since parsers treat duplicates differently.

A parse error usually points near the real mistake: look for a missing comma or quote just before it.

Designing payloads

• Write dates and times as ISO 8601 strings, preferably in UTC with a Z or an explicit offset. See Dates, Times and Time Zones.
• JavaScript-based parsers read all numbers as 64-bit floating point, so integers above 9007199254740991 lose precision. Send IDs as strings, and money as integer minor units (cents) or as strings.
• Decide what null and a missing field each mean (unknown, cleared, not sent) and document it. This matters for partial updates.
• Use one naming style, such as camelCase or snake_case, across the whole API, and consistent shapes: a list endpoint should always return an array or an agreed envelope such as { "items": [], "total": 0 }.
• Give errors a consistent structure too. Problem Details (RFC 9457) is a standard one to look at.
• Return only the fields the client needs, and never include secrets.

Tools

# Bash: pretty-print and query with jq (a separate install)
curl -s https://example.com/api/users | jq '.[0].name'

# PowerShell: built-in
$u = Invoke-RestMethod https://example.com/api/users/42
$u.name
$u | ConvertTo-Json -Depth 5     # default depth is only 2, deeper objects get cut off

Editors can format and validate JSON. JSON Schema describes the expected structure so payloads can be validated automatically. For other formats and the general topic see Data Serialization, and validate incoming data as described in Input Validation.

Try it

Call a public JSON API of your choice and save the response to a file. Extract one nested value with jq or PowerShell. Then break the file deliberately (add a trailing comma, use single quotes) and read the parser’s error message each time.