What is JSON? A complete guide

The whole JSON format in one page: the six kinds of value, the rules, the traps, and what JSON cannot do.

Updated 2026-11-04 · 9 minute read

JSON is a way to write data as text. Almost every program that talks to another program over a network uses it. This page explains the whole format. It is short, because JSON itself is short. The standard fits on a few pages, and that is the point of it.

Where JSON came from

Douglas Crockford took a small part of the JavaScript language in 2001 and wrote down the rules. The format became a standard in 2013, and the current standard is RFC 8259. The name means JavaScript Object Notation.

Two things made it win over XML. It is shorter, and a program can read it with one small function. A person can also read it, which matters when something goes wrong at three in the morning.

The six kinds of value

A JSON document holds exactly one value. That value is one of six kinds.

1. An object

An object holds pairs. Each pair has a key and a value. The key must be text in double quotation marks.

{
  "name": "Ada",
  "age": 36,
  "active": true
}

The order of the pairs carries no meaning. A program may give them back in another order, and the data is the same.

2. An array

An array holds a list of values, in order. The order does matter.

["red", "green", "blue"]

The values do not have to be the same kind:

[1, "two", true, null, {"four": 4}]

3. Text

Text goes in double quotation marks. Single quotation marks are not allowed.

"Hello, world"

Some characters must be written with a backslash:

4. A number

42
-17
3.14
6.02e23

JSON has one kind of number. There is no separate integer. A number must not start with a +, must not start with a 0 before another digit, and must not be written as .5 or 5.. Write 0.5 and 5.0.

JSON has no NaN and no Infinity. Many programs write them anyway, and then the file is not JSON. The usual answer is to write null instead.

5. True and false

true
false

Lower case only. True is a Python word, not a JSON word.

6. Null

null

null means "a value is here, and it is empty". It is not the same as the key being absent. Programs often treat the two differently, and that difference causes real faults.

The rules in full

That is the whole format. The rules that catch people are these:

1. A comma separates items. It does not end them. [1, 2, 3,] is wrong. The last comma has nothing after it.
2. Keys need double quotation marks. {name: "Ada"} is JavaScript, not JSON.
3. No comments. The format has no // and no /* */.
4. The file holds one value. Two objects in a row is not a JSON file. It may be a JSON Lines file, which is a different thing.
5. White space is free. Spaces, tabs and new lines between values mean nothing. This is why a formatter can make a file readable without changing the data.

What JSON cannot hold

This is the part that surprises people who come from other formats.

A date. JSON has no date. Everybody writes a date as text, usually as "2026-11-04T09:30:00Z", which is the ISO 8601 form. Use that form. A date written as 04/11/2026 means two different days on two sides of the world.

A big number. A number in JSON may hold any number of digits, but most programs read it into a 64-bit floating point number. Above about 9 thousand million million, the digits change. Many systems write a large identifier as text for this reason. See big numbers in JSON.

Binary data. There is no way to write raw bytes. The usual answer is base64 text, which makes the data about a third bigger.

A reference to itself. An object cannot point at another part of the same document. Every value is written out in full.

A comment. See comments in JSON.

Two documents that look the same

{"a": 1, "b": 2}

{
  "b": 2,
  "a": 1
}

These two hold the same data. The white space means nothing, and the order of the keys in an object means nothing. A good comparison tool knows this and does not report a difference. The Compare action in this tool follows that rule.

But these two are not the same:

{"items": [1, 2]}

{"items": [2, 1]}

The order inside an array is part of the data.

How to check a file

Three questions answer almost every problem:

1. Is it valid? Paste it into the viewer. If it is not valid, the status bar gives the line and the column of the first fault, and the common errors page tells you what it means.
2. What shape is it? Open the Viewer tab and close every branch (Collapse all), then open one level at a time. The shape appears in seconds, even in a file of 100 MB.
3. Where is the part I need? Press / and search, or write a JSONPath such as $..email.

A word about size

JSON is text, so it is bigger than a binary format, and a program must read every character. For a message between two services this costs nothing. For a file of several hundred megabytes it matters, and the usual answers are to compress it on the wire, to split it into JSON Lines, or to move to a binary format.

For reading and understanding a large file, the real limit is not the format. It is the tool. Most web viewers build one element in the page for every value in the file, which is why they stop answering at about 20 MB. This tool does not do that, so a file of 120 MB opens in about a second. See large JSON files.

In short

• One value for each document, and six kinds of value.
• Keys and text need double quotation marks.
• No trailing comma, no comment, no date, no NaN.
• White space and the order of keys carry no meaning.
• The order inside an array does carry meaning.

Read next