JSON (JavaScript Object Notation)

A lightweight, human-readable text format for representing structured data as key-value pairs and ordered lists.

---

What is it?

JSON (JavaScript Object Notation) is a text-based data format that stores information as key-value pairs and arrays. It was derived from JavaScript’s object syntax in the early 2000s, but despite the name, JSON is completely language-independent --- it works in Python, Java, Ruby, Go, and virtually every other modern programming language.¹

JSON has become the lingua franca of the web. When a weather app fetches today’s forecast, the server almost certainly sends the data back as JSON. When a configuration file needs to store settings, JSON is one of the most common choices. When an AI agent calls an API, the request and response are usually formatted in JSON.²

Its popularity comes from a rare combination: it is simple enough for humans to read and edit by hand, yet structured enough for machines to parse and generate efficiently. This dual readability is what sets it apart from older formats like XML.³

In plain terms

JSON is like a labelled filing cabinet. Each drawer has a name (the key) and contains something (the value) --- a single fact, a list of items, or another smaller cabinet nested inside. Anyone who knows the drawer names can find what they need.

---

At a glance

JSON structure at a glance (click to expand)

graph TD
    ROOT[JSON Document] --> OBJ[Object]
    ROOT --> ARR[Array]
    OBJ --> KV1[key: string value]
    OBJ --> KV2[key: number value]
    OBJ --> KV3[key: nested object]
    OBJ --> KV4[key: array value]
    ARR --> ITEM1[Item 1]
    ARR --> ITEM2[Item 2]
    ARR --> ITEM3[Item N]

Key: A JSON document is either an object (curly braces, containing key-value pairs) or an array (square brackets, containing an ordered list of values). Values can nest recursively --- objects inside objects, arrays inside arrays.

---

How does it work?

Key-value pairs

The fundamental unit of JSON is a key-value pair. The key is always a string in double quotes. The value can be one of six types: string, number, boolean (true/false), null, object, or array.¹

For example:

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

The colon separates key from value. Pairs are separated by commas.

Think of it like...

A key-value pair is a question and answer on a form. The key is the label (“Name:”), and the value is what you fill in (“Ada Lovelace”). The form only makes sense if every field has a label.

Objects

A JSON object is a collection of key-value pairs wrapped in curly braces { }. Objects are unordered --- the pairs can appear in any sequence, and the meaning does not change.¹

{
  "city": "Lausanne",
  "country": "Switzerland",
  "population": 140000
}

Each key within an object must be unique. You cannot have two keys called "city" in the same object.

Arrays

A JSON array is an ordered list of values wrapped in square brackets [ ]. Unlike objects, the order of items in an array matters.¹

{
  "languages": ["Python", "JavaScript", "Rust"]
}

Arrays can contain any JSON value type, including other arrays or objects. This is how JSON represents collections --- a list of users, a set of coordinates, a sequence of events.

Example (click to expand)

A to-do list as a JSON array of objects:

{
  "tasks": [
    { "id": 1, "title": "Buy groceries", "done": false },
    { "id": 2, "title": "Write report", "done": true },
    { "id": 3, "title": "Call dentist", "done": false }
  ]
}

Each task is an object with its own key-value pairs. The array preserves the order of tasks.

Nesting

JSON values can be nested to any depth --- objects inside objects, arrays inside arrays, objects inside arrays. This recursive structure lets JSON represent complex, hierarchical data.³

{
  "album": "Kind of Blue",
  "artist": "Miles Davis",
  "tracks": [
    {
      "title": "So What",
      "duration": 545,
      "soloists": ["Miles Davis", "John Coltrane"]
    },
    {
      "title": "Freddie Freeloader",
      "duration": 588,
      "soloists": ["Wynton Kelly", "Miles Davis"]
    }
  ]
}

Think of it like...

Nesting is like Russian dolls. The outermost doll (the root object) contains smaller dolls (nested objects and arrays), each of which can contain even smaller dolls. You open one level at a time to find what you need inside.

Data types

JSON supports exactly six value types:¹

Type	Example	Notes
String	"hello"	Must use double quotes, not single
Number	42, 3.14, -7	No distinction between integer and float
Boolean	true, false	Lowercase only
Null	null	Represents absence of a value
Object	{ "a": 1 }	Unordered key-value pairs
Array	[1, 2, 3]	Ordered list of values

Note what JSON does not support: comments, dates (they must be encoded as strings), functions, or undefined. These constraints keep the format simple and unambiguous.¹

Key distinction

JSON looks like JavaScript, but it is not JavaScript. JSON keys must be in double quotes. JSON cannot contain functions or trailing commas. A JavaScript object is valid code; JSON is a data format that any language can read.²

Parsing and serialisation

Converting a JSON string into a data structure your program can work with is called parsing (or deserialisation). Converting a data structure back into a JSON string is called serialisation (or stringification).⁴

For example, in JavaScript:

// Parsing: JSON string --> JavaScript object
const data = JSON.parse('{"name": "Ada", "born": 1815}');
 
// Serialisation: JavaScript object --> JSON string
const text = JSON.stringify({ name: "Ada", born: 1815 });

Every major programming language has built-in or standard-library support for both operations.

Real-world example: graph.json (click to expand)

This knowledge system stores its concept graph in a file called graph.json. Here is a simplified excerpt showing how one concept card is represented:

{
  "concepts": {
    "apis": {
      "title": "APIs (Application Programming Interfaces)",
      "level": "topic",
      "parent": "client-server-model",
      "children": ["http-protocol", "json", "rest-api"],
      "related": ["frontend", "backend"]
    }
  }
}

Each concept is a key in the outer object. Its value is a nested object containing metadata as key-value pairs and relationships as arrays. This is JSON doing exactly what it does best: representing structured, hierarchical data in a format that both humans and scripts can read.

---

Why do we use JSON?

Key reasons

1. Human-readable. Unlike binary formats, you can open a JSON file in any text editor and immediately understand its structure. This makes debugging and manual editing practical.

2. Universal compatibility. JSON is supported natively or via standard libraries in virtually every programming language, making it the default choice for data exchange between systems.¹

3. Lightweight. Compared to XML, JSON uses fewer characters to represent the same data --- no closing tags, no attributes. A JSON payload is typically 30-50% smaller than its XML equivalent.³

4. API standard. JSON is the dominant format for web APIs. When a client sends a request to a server and receives data back, that data is almost always JSON.²

---

When do we use JSON?

• When exchanging data between a client and server via an API
• When storing configuration for applications, tools, or frameworks (e.g., package.json, tsconfig.json)
• When saving structured data to a file that both humans and machines need to read
• When defining schemas or data models that describe the shape of other data
• When working with NoSQL document databases that store records as JSON-like documents

Rule of thumb

If the data is structured (not free-form prose) and needs to travel between systems or be read by both humans and code, JSON is almost certainly the right format.

---

How can I think about it?

The recipe card

A recipe card is a real-world JSON object.

• The card itself is the object (wrapped in { })
• “title” is a key, "Chocolate Cake" is its string value
• “servings” is a key, 8 is its number value
• “ingredients” is a key, its value is an array --- an ordered list of items
• “oven” is a key, its value is a nested object: { "temp": 180, "unit": "C" }
• “vegetarian” is a key, true is its boolean value

Every piece of information has a label (key) and a value. You can find any fact by knowing its label --- just like accessing recipe.oven.temp in code.

The address book

A paper address book is a JSON array of objects.

• The book itself is the array (wrapped in [ ]) --- an ordered list of entries
• Each entry is an object with keys like "name", "phone", "address"
• The address field is a nested object: { "street": "...", "city": "...", "zip": "..." }
• Some entries have an email key, others do not --- JSON allows this flexibility
• The entire book is serialisable --- you could copy it as text, send it to someone, and they could parse it back into a usable contact list

This maps directly to a common API pattern: requesting a list of records from a server and receiving a JSON array of objects.

---

Concepts to explore next

Concept	What it covers	Status
apis	How JSON is used as the data format in API requests and responses	complete
structured-data-vs-prose	When structured formats like JSON are better than free text	stub
knowledge-graphs	How JSON can represent nodes and edges in a connected data system	stub
machine-readable-formats	The family of formats (JSON, XML, YAML, CSV) that machines can parse	stub

Some cards don't exist yet

A broken link is a placeholder for future learning, not an error.

---

Check your understanding

Test yourself (click to expand)

1. Explain what JSON is and why it matters for web development, in terms a non-programmer could understand.
2. Name the six data types that JSON supports and give an example value for each.
3. Distinguish between a JSON object and a JSON array. When would you use each?
4. Interpret the following JSON and describe what it represents:

   { "city": "Berlin", "population": 3700000, "capital": true }

5. Connect JSON to the concept of APIs: why is JSON the preferred format for sending data between a client and a server?

---

Where this concept fits

Position in the knowledge graph

graph TD
    MRF[Machine-Readable Formats] --> JSON[JSON]
    MRF --> XML[XML]
    MRF --> YAML[YAML]
    MRF --> CSV[CSV]
    API[APIs] -.->|uses| JSON
    JSON -.->|related| SDvP[Structured Data vs Prose]
    JSON -.->|related| KG[Knowledge Graphs]
    style JSON fill:#4a9ede,color:#fff

Related concepts:

• apis --- JSON is the standard data format for web API requests and responses; the apis card references JSON as a child concept
• structured-data-vs-prose --- JSON is one answer to the question “when should data be structured rather than free text?”
• knowledge-graphs --- graph data (nodes, edges, properties) is commonly serialised as JSON

---

Sources

---

Further reading

Resources

• Introducing JSON (json.org) --- The official specification with syntax diagrams; the definitive reference
• JSON for Beginners (freeCodeCamp) --- Plain-English walkthrough with practical JavaScript examples
• Working with JSON (MDN Web Docs) --- Hands-on tutorial fetching and parsing JSON in a web application
• What is JSON? Complete Beginners Guide (JSON Web Tools) --- Comprehensive 2026 guide covering syntax, validation, and common use cases
• Understanding JSON: A Beginner’s Guide (Liquid Technologies) --- Four-part series going from basics to advanced nesting and schema validation

Footnotes

1. json.org. (2024). Introducing JSON. ECMA International. ↩ ↩² ↩³ ↩⁴ ↩⁵ ↩⁶ ↩⁷

2. Adhikary, T. (2021). JSON for Beginners --- JavaScript Object Notation Explained in Plain English. freeCodeCamp. ↩ ↩² ↩³

3. Mozilla Developer Network. (2024). Working with JSON. MDN Web Docs. ↩ ↩² ↩³

4. Mozilla Developer Network. (2024). JSON.parse(). MDN Web Docs. ↩