Understanding JSON: A Complete Beginner's Guide

What is JSON?

JSON — JavaScript Object Notation — is a lightweight, text-based data interchange format. It was designed to be easy for humans to read and write, and easy for machines to parse and generate. The official specification lives at json.org and is standardised as ECMA-404 and RFC 8259.

Despite the "JavaScript" in the name, JSON is entirely language-independent. Python, Java, C#, Ruby, Go, PHP, and hundreds of other languages have built-in or library support for parsing and generating JSON.

A Brief History

JSON was invented by Douglas Crockford around 2001 as a simpler alternative to XML for data interchange in web applications. The state.json.org website went live in 2002. The format gained rapid adoption because it maps directly to data structures that all programming languages support (dictionaries/maps and arrays/lists).

It was standardised by ECMA International as ECMA-404 in 2013, and as RFC 7159 (later updated to RFC 8259) by the IETF. Today, JSON is effectively the default format for REST APIs, configuration files, and data storage in document databases like MongoDB.

JSON Data Types

JSON supports exactly six data types:

String

A sequence of characters in double quotes. Unicode characters are supported.

"Hello, World!"
"user@example.com"
"2024-02-08"

Number

An integer or floating-point number. No distinction between integers and floats in JSON.

42
3.14159
-273.15
1.5e10

Boolean

Either true or false (lowercase only).

true
false

Null

Represents the absence of a value (lowercase only).

null

Object

A collection of key-value pairs enclosed in curly braces. Keys must be strings.

{"name": "Alice", "age": 30}

Array

An ordered list of values enclosed in square brackets.

[1, 2, 3, "four", true]

JSON Objects

An object is a collection of zero or more key-value pairs. Keys must be strings in double quotes. Values can be any JSON type. Pairs are separated by commas. The last pair must not have a trailing comma.

{
  "firstName": "Alice",
  "lastName": "Smith",
  "age": 28,
  "isActive": true,
  "address": null
}

Objects are the workhorse of JSON. They represent entities — a user, a product, a configuration, an API response. Think of them as dictionaries or hash maps: you look up a value by its key.

JSON Arrays

An array is an ordered sequence of values. Values are separated by commas and can be of any JSON type, including mixed types (though mixing types is unusual in practice).

["apple", "banana", "cherry"]

[1, 2, 3, 4, 5]

[true, false, null, 42, "hello"]

Arrays are useful for lists of items: users, products, log entries, coordinates, or any sequence of values.

Nesting Objects and Arrays

JSON's real power comes from nesting. Objects can contain other objects or arrays; arrays can contain objects. There is no practical limit to the depth of nesting.

{
  "user": {
    "id": 12345,
    "name": "Alice Smith",
    "email": "alice@example.com",
    "roles": ["admin", "editor"],
    "address": {
      "street": "123 Main St",
      "city": "Springfield",
      "country": "US"
    },
    "recentOrders": [
      {"orderId": "ORD-001", "total": 59.99},
      {"orderId": "ORD-002", "total": 129.50}
    ]
  }
}

This example shows an object containing an array (roles), a nested object (address), and an array of objects (recentOrders). This is the typical structure of a real API response.

JSON vs XML

Before JSON's rise, XML was the dominant data interchange format. The two have very different philosophies:

Property	JSON	XML
Verbosity	Compact	Verbose (opening and closing tags)
Human readability	High	Moderate (noisy with tags)
Comments	Not supported	Supported (<!-- -->)
Attributes	Not a concept	Element attributes
Arrays	Native syntax	Workaround (repeated elements)
Schema validation	JSON Schema	XSD, DTD, RelaxNG
Best for	Web APIs, config, storage	Documents, enterprise integrations, SOAP

For most web API use cases, JSON is the clear winner in terms of simplicity and payload size. XML remains relevant for document-oriented applications (DOCX, SVG, EPUB are XML-based) and enterprise systems.

Real-World Use Cases

REST API Responses

The overwhelming majority of REST APIs return JSON. When your JavaScript code calls fetch() and gets a response, it almost certainly returns JSON that you parse with response.json().

Configuration Files

Many tools use JSON for configuration: package.json (Node.js project config), tsconfig.json (TypeScript config), settings.json (VS Code settings). The format is human-readable and has wide tooling support.

Data Storage

Document databases like MongoDB store data as BSON (Binary JSON). Many SQL databases now have native JSON column types (PostgreSQL, MySQL, SQLite). JSON files are often used as simple data stores for small projects.

Logging

Structured log formats (like those used by cloud logging services) often use JSON: one JSON object per log line, making logs easy to search and aggregate programmatically.

JSON5 and JSONC Variants

Standard JSON's restrictions (no comments, no trailing commas, double quotes only) can be inconvenient for configuration files that humans edit frequently. Two variants address this:

JSONC (JSON with Comments): Adds single-line (//) and multi-line (/* */) comment support. Used by Visual Studio Code's settings files. A JSONC document must be parsed with a JSONC-aware parser.

JSON5: A superset of JSON that also adds: trailing commas, single-quoted strings, unquoted keys (as valid JS identifiers), hexadecimal numbers, and multi-line strings. See the JSON5 specification for details. Like JSONC, JSON5 requires a compatible parser.

For interoperability (APIs, storage), always use standard JSON. Use JSONC or JSON5 only in human-edited configuration contexts where the parser is known to support the variant.