What is a JSON Document?

A JSON document is structured text made of objects, arrays, strings, numbers, booleans and null. Syntax, an example and the mistakes that break parsing.

What is a JSON document?

A JSON document is a text file or message written in JavaScript Object Notation: a small, human-readable format for structured data built from objects, arrays, strings, numbers, booleans and null. APIs, configuration files and document databases use it because every major language can parse it. The format is defined in RFC 8259 and ECMA-404. For a first walk through the syntax, see JSON: a beginner's guide.

The value types

RFC 8259 says a JSON value must be an object, array, number or string, or one of the three literal names true, false and null.

  • Object: { "key": value }, a set of name and value pairs. Names are always strings.
  • Array: [ value, value ], an ordered list.
  • String: "hello", text in double quotes.
  • Number: 42, 3.14, 1e10. The format does not separate integers from decimals.
  • Boolean: true or false, lowercase and without quotes.
  • Null: null, the explicit absence of a value.

There is no date type, no binary type and no comment syntax. Dates and binary data travel as strings by convention.

An example

{
  "id": "order_42",
  "customer": { "name": "Alice", "verified": true },
  "items": [
    { "sku": "WIDGET-1", "qty": 2, "price": 9.99 },
    { "sku": "GIZMO-7", "qty": 1, "price": 19.95 }
  ],
  "shipped_at": null,
  "tags": ["priority", "gift"]
}

Every value is one of the types above, and objects and arrays can nest as deep as needed. The same text parses to the same structure in any language.

Where you meet JSON documents

  • APIs: request and response bodies, usually sent with the media type application/json. See API payloads and, for the remote-call style that wraps its messages in JSON, JSON-RPC.
  • Configuration: package.json and tsconfig.json are everyday examples.
  • Document databases: MongoDB, Firestore and DynamoDB all work with document-shaped data.
  • Logs: structured logging writes one JSON object per line.
  • Structured data for search: JSON-LD embeds schema.org data in a web page.

Mistakes that break JSON

  • Trailing commas. {"a":1,} is invalid. JavaScript tolerates it, JSON does not.
  • Comments. JSON has none. Formats such as JSON5 and JSONC add them, but a strict parser rejects them.
  • Single quotes or unquoted names. Names and strings need double quotes.
  • Large integers. RFC 8259 notes that software commonly uses IEEE 754 double precision numbers, and JavaScript's JSON.parse does too, so integers above 2^53 - 1 (9007199254740991) can lose precision. Send 64-bit IDs as strings.
  • Duplicate names. The RFC says names within an object should be unique and that behaviour is unpredictable otherwise.
  • Wrong encoding. JSON text exchanged between systems must be UTF-8 according to the RFC.

JSON compared with other formats

  • YAML is easier to write by hand and allows comments, which is why CI and Kubernetes files use it. It is also whitespace-sensitive.
  • XML suits document markup and older enterprise systems, at the cost of more verbose syntax.
  • Protocol Buffers are binary and need a schema, which suits high-volume RPC but is harder to read.

To describe what a valid document looks like, use JSON Schema. The LoadFocus blog explains it in what is JSON Schema.

Testing JSON endpoints

A JSON endpoint can return 200 with the wrong body. LoadFocus API monitoring checks the status code, response body, headers and response time on a schedule, and lists a JSON schema match as an example check. Free checks run every 5 minutes. For how an endpoint behaves with many callers at once, run an API load test. More on the practice is in API monitoring.

FAQ: JSON documents

What is the difference between JSON and a JavaScript object?

JSON is text. A JavaScript object is a value in memory. JSON is stricter: names and strings need double quotes, and it cannot hold functions, undefined or comments. JSON.parse turns the text into an object.

How do I validate a JSON document?

Run it through a parser. On the command line, jq . file.json prints the document or the first syntax error. To check structure as well as syntax, validate against a JSON Schema.

How big can a JSON document be?

The format sets no limit. Limits come from the parser, which may load the whole document into memory, and from the servers and gateways in between. For very large data sets, send one JSON object per line (NDJSON) or use a binary format.

How do I store a date in JSON?

JSON has no date type. The usual convention is an ISO 8601 string such as "2026-05-07T08:22:00Z". Both sides need to agree on it.

Should I use JSON or YAML for configuration?

Use JSON for files generated by tools. Use YAML for files people edit by hand when comments matter. Many ecosystems have a convention, so follow it.

How fast is your website?

Elevate its speed and SEO seamlessly with our Free Speed Test.

Free Website Speed Test

Analyze your website's load speed and improve its performance with our free page speed checker.