What Is JSON?

What JSON looks like

{
  "id": 4021,
  "name": "Ada Lovelace",
  "active": true,
  "manager": null,
  "roles": ["admin", "billing"],
  "address": {
    "city": "London",
    "postcode": "EC1A 1BB"
  }
}

That is an object: a set of names, each followed by a colon and a value, separated by commas and wrapped in braces. The values here show every type JSON has. Because it is plain text, the same document can be written by a Python server, sent over HTTP, and read by a JavaScript page or a Swift app without either side knowing what the other is written in. That independence, plus being easy to read, is why JSON displaced XML as the default format for APIs.

The six data types

Any of the six may be the whole document. "hello", 42 and null are each valid JSON on their own, although APIs nearly always send an object or an array at the top level. Arrays and objects nest inside each other to any depth.

Notice what is missing. There is no date type, so dates are sent as strings, usually in ISO 8601 form such as "2026-03-14T09:30:00Z", or as a number of seconds that an epoch converter can read. There is no type for binary data, so files are carried as Base64 strings. And there is no way to write a comment.

The rules that catch people out

JSON was derived from JavaScript, and most JSON errors come from writing JavaScript out of habit. All of the following are valid in a JavaScript file and rejected by a JSON parser.

A parser stops at the first problem and reports a position, so the fix is usually one character near that point. The JSON validator shows the line and column and names the likely cause.

Two problems a parser will not report

Large numbers lose precision. The grammar allows a number of any size, but most parsers store numbers as 64-bit floating point, which holds integers exactly only up to 9,007,199,254,740,991. A 19-digit database ID such as 1234567890123456789 is read without error and silently becomes 1234567890123456800. This is why many APIs send large identifiers as strings.

Duplicate names are accepted. {"role": "user", "role": "admin"} parses in every mainstream library. Most keep the last value, a few keep the first, and when two systems disagree the result can be a security bug. The specification says names should be unique; nothing enforces it.

JSON and JavaScript objects are not the same thing

A JavaScript object is a live value in memory. JSON is a string of characters that describes one. You move between them with two functions, and every language has an equivalent pair.

// JavaScript
const text = JSON.stringify({ id: 1, tags: ["a", "b"] });   // object → JSON text
const data = JSON.parse(text);                             // JSON text → object

# Python
import json
text = json.dumps({"id": 1, "tags": ["a", "b"]})
data = json.loads(text)

The conversion is lossy in one direction. JSON.stringify drops properties whose value is undefined or a function, turns NaN into null, and writes a Date as a string that JSON.parse does not turn back into a date. If a field vanishes between your code and the server, look there first.

How APIs send JSON

A JSON body is labelled with the media type application/json. A request that carries one must say so, and a response that carries one will:

POST /v1/users HTTP/1.1
Host: api.example.com
Content-Type: application/json
Accept: application/json

{"name": "Ada Lovelace", "roles": ["admin"]}

Leaving out the Content-Type header is the most common reason a correct body is rejected: the server assumes form data, fails to parse it, and answers 400 or 415. A body that is valid JSON but breaks the API's own rules, such as a missing required field, is answered with 422. The encoding is UTF-8; the specification requires it for JSON exchanged between systems, so no charset parameter is needed.

You will also meet relatives of the plain media type: application/problem+json for standardised error bodies, application/ld+json for linked data, and newline-delimited JSON for streams, where each line is a separate document. The MIME types reference lists them. To send a JSON body from a terminal, see the curl POST JSON example.

JSON next to the alternatives

Converting between them is routine: the YAML to JSON, JSON to CSV and XML formatter tools each handle one pair. To explore a large response, the JSON viewer shows it as a collapsible tree, and JSON compare finds what changed between two versions.

References

• RFC 8259: The JSON Data Interchange Format — The current specification, including the UTF-8 requirement and the notes on numbers and duplicate names.
• ECMA-404: The JSON data interchange syntax — The grammar as an Ecma standard.
• json.org — The original description, with railroad diagrams of the whole syntax.
• MDN: JSON — JSON.parse and JSON.stringify, and how JSON differs from JavaScript.

These links leave api-tester.com, which is independent of the organisations they point to.

Frequently asked questions