What Is JSON? A Beginner's Guide With Examples

When a weather app shows a forecast, it has usually just received a small piece of text from a server describing the temperature, wind and conditions. That text is very likely JSON. It is the most common format for sending structured data between programs, and it is simple enough to read without being a programmer.

In short: JSON is a plain-text way of writing structured data as names and values. It is strict about quotes and commas, which is where almost every error comes from.

What JSON looks like

{
  "name": "Ada Lovelace",
  "born": 1815,
  "mathematician": true,
  "languages": ["English", "French"],
  "address": {
    "city": "London",
    "country": "United Kingdom"
  },
  "website": null
}

That is a complete, valid JSON document. It describes one thing (a person) using named values. Notice that it reads almost like a labelled list.

The six kinds of value

Arrays and objects can contain any of the other types, including more arrays and objects. That nesting is how JSON describes complicated data with so few rules.

The rules

• Names (keys) are strings in double quotes, followed by a colon.
• Items are separated by commas, with no comma after the last one.
• Strings use double quotes, never single quotes.
• Whitespace between items is ignored, so indentation is for humans only.
• There are no comments.

Where you will meet JSON

• APIs: when apps and websites request data from a server, the reply is usually JSON.
• Configuration files: many tools store settings in files such as package.json or settings.json.
• Data exports: services that let you download your data often provide it as JSON.
• Structured data on web pages: search engines read a JSON-based format called JSON-LD to understand what a page is about.

The errors everyone makes

JSON is strict, and one misplaced character makes the whole document invalid. These account for most failures:

{ "a": 1, "b": 2, }      ← trailing comma
{ 'a': 1 }               ← single quotes
{ a: 1 }                 ← key without quotes
{ "a": 1 "b": 2 }        ← missing comma
{ "path": "C:\temp" }    ← backslash must be written as \\

When something will not parse, paste it into the JSON Formatter & Validator. It reports the line and column where the problem is and, once fixed, indents the document so its structure is easy to see.

Formatted or minified?

The example above is formatted: indented, one item per line. The same data can be minified onto a single line with the whitespace removed:

{"name":"Ada Lovelace","born":1815,"mathematician":true}

Both mean exactly the same thing. Minified JSON is smaller, so it is used when sending data over a network. Formatted JSON is for people. Converting between the two never changes the data.

JSON compared with XML, CSV and YAML

• XML is older and more verbose, using opening and closing tags. It is still common in documents and enterprise systems.
• CSV is ideal for simple tables with rows and columns, but cannot represent nested data.
• YAML expresses the same structures as JSON using indentation instead of brackets, and allows comments. It is popular for configuration files.

JSON's position in the middle, structured but simple, is why it became the default for the web.

A realistic example, explained

{
  "orderId": 1042,
  "paid": true,
  "customer": { "name": "Ana Costa", "email": "ana@example.com" },
  "items": [
    { "sku": "TEA-01", "qty": 2, "price": 4.5 },
    { "sku": "MUG-07", "qty": 1, "price": 9 }
  ],
  "coupon": null
}

• The outer curly brackets make one object: a set of names and values.
• orderId is a number and paid is a boolean. Neither is wrapped in quotes.
• customer holds another object, nested inside the first.
• items is an array, an ordered list in square brackets. Each entry is itself an object.
• coupon is null, meaning “no value”. That is different from an empty string or from leaving the name out.

Reading and writing JSON in code

Every mainstream language can turn JSON text into its own data structures and back. In JavaScript:

const order = JSON.parse(text);      // text to object
console.log(order.items[0].sku);     // "TEA-01"
const out = JSON.stringify(order, null, 2);  // object to formatted text

In Python:

import json
order = json.loads(text)             # text to dict
print(order["items"][0]["sku"])      # TEA-01
out = json.dumps(order, indent=2)    # dict to formatted text

Both will stop with an error message naming a line and position if the text is not valid JSON. That position is where the parser gave up, which is often just after the real mistake, so look at the characters immediately before it.

Valid and invalid at a glance

Why JSON became the default

• For it: readable by people, supported in every programming language, and compact compared with XML.
• For it: maps directly onto the lists and dictionaries programmers already use.
• Against it: no comments, no dates as a built-in type, and no tolerance for small slips.
• Against it: awkward for large tables, where CSV is smaller and opens in a spreadsheet.

To move between the two, use the CSV to JSON Converter. To find the slip in a file that will not parse, paste it into the JSON Formatter, which points to the line with the problem.