What is JSON? A beginner's guide to JavaScript Object Notation

JSON, JavaScript Object Notation, is a text format for representing structured data: objects, lists, strings, numbers, booleans and a null value, written in a syntax small enough to read in an afternoon and strict enough that every language can parse it the same way. It is not tied to JavaScript despite the name.

Every mainstream language ships a JSON parser in its standard library or a one-line install, which is the actual reason it won: not because it is elegant, but because it is boring and portable.

What it looks like

{
  "name": "Ada Lovelace",
  "age": 36,
  "isEmployed": true,
  "skills": ["mathematics", "writing"],
  "address": { "city": "London", "country": "UK" },
  "nickname": null
}

An object is { } holding key-value pairs, an array is [ ] holding an ordered list, and everything else nests inside those two containers. That is the entire shape of JSON: two container types and a handful of value types inside them.

The six value types, no more and no fewer

A JSON value is a string, a number, a boolean, null, an array, or an object. Nothing else exists in the specification.

There is no date type, no undefined, no comment syntax, and no way to represent a function. A date becomes a string in a format both sides agree on (usually ISO 8601), and a value that would be undefined in JavaScript is simply left out of the object rather than written in. JSON Data Types Explained covers each of the six in more detail, including the edge cases that trip up a naive parser.

Why it replaced XML for most APIs

XML wraps every value in opening and closing tags, supports attributes on top of that, and needs a separate schema language to describe what is valid. JSON’s containers are two characters each, and values are typed without a tag telling you so.

The shape of a JSON document also mirrors the shape of the data structure a program actually uses: parsing it into a language’s native object literal is close to a direct copy, where an XML document usually needs its own object model translated on top of it. That is a genuine, measurable difference in payload size and parsing cost, which is why REST APIs settled on JSON once it existed. See JSON vs XML for a closer, more specific comparison.

Where you will actually run into it

• REST API responses and requests. The dominant format for Content-Type: application/json bodies, both directions.
• Configuration files. package.json, tsconfig.json, and most modern tool configs, though YAML is common here too; see JSON vs YAML for when each fits better.
• NoSQL and document databases. MongoDB documents are stored as BSON, a binary superset of JSON, and most document stores accept and return JSON directly.
• Log lines and data pipelines, one JSON object per line, a format usually called NDJSON. Common JSON Use Cases walks through this and the others with real shapes.
• Browser storage. localStorage only stores strings, so anything structured gets JSON.stringifyd going in and JSON.parsed coming back out.

Working with it

Paste a document into the JSON Formatter to pretty print it, or the JSON Validator to check it against the specification with a line and column on the exact character that broke. Neither uploads what you paste; both run entirely in your browser. Once the basics make sense, the JSON Cheat Sheet is a one-page reference for the syntax rules above, worth keeping open in a tab or downloading for offline reference.