What is JSON? A Complete Beginner's Guide

JSON (JavaScript Object Notation) is a lightweight, text-based format for storing and exchanging data. Despite having "JavaScript" in its name, JSON is completely language-independent and is supported natively by virtually every modern programming language - from Python and Java to Ruby, Go, and PHP.

If you have ever used a web application, consumed a REST API, or worked with configuration files, you have almost certainly worked with JSON - even if you did not realise it. It is the backbone of modern data exchange on the internet.

A Brief History of JSON

JSON was created by Douglas Crockford in the early 2000s as a simpler alternative to XML for exchanging data between a server and a web browser. Crockford noticed that JavaScript already had a built-in way to represent data structures using object and array literals, and he formalised this into a specification.

The first JSON website went live in 2002, and the format was standardised as ECMA-404 in 2013 and RFC 8259 in 2017. Before JSON became dominant, XML was the primary format for APIs - but JSON's simplicity and smaller payload size made it rapidly replace XML in most web applications throughout the 2000s and 2010s.

The Basic Structure of JSON

A JSON document is built from two fundamental structures:

• Objects - An unordered collection of key-value pairs, enclosed in curly braces {}. Each key must be a string in double quotes, followed by a colon and the value.
• Arrays - An ordered list of values, enclosed in square brackets []. Values are separated by commas.

Here is a real-world example of a JSON object representing a user profile:

{
  "id": 1042,
  "name": "Alice Johnson",
  "email": "alice@example.com",
  "age": 30,
  "isActive": true,
  "balance": 1250.75,
  "address": {
    "street": "123 Main St",
    "city": "New York",
    "state": "NY",
    "zip": "10001",
    "country": "USA"
  },
  "tags": ["developer", "designer", "admin"],
  "lastLogin": "2024-01-14T09:30:00Z",
  "preferences": null
}

JSON Data Types

JSON supports exactly six data types. Understanding these is essential because JSON is strictly typed - unlike JavaScript itself, which allows many implicit type conversions.

1. String

Text enclosed in double quotes. Single quotes are NOT valid in JSON. Strings support Unicode and can contain escape sequences like \n (newline), \t (tab), and \" (escaped quote).

"name": "Alice Johnson"
"emoji": "Hello ❤"
"multiline": "Line one\nLine two"

2. Number

Integer or floating-point numbers. JSON does not distinguish between integers and decimals - both are just "numbers". There is no separate type for BigInt, complex numbers, or special values like Infinity or NaN.

"age": 30
"price": 19.99
"temperature": -5.2
"distance": 1.5e10

3. Boolean

Either true or false - lowercase only. Unlike JavaScript, JSON does not accept True, False, 1, or 0 as booleans.

"isActive": true
"isDeleted": false

4. Null

Represents the intentional absence of a value. Use null when a field exists in the schema but has no value - this is different from omitting the field entirely.

"middleName": null
"deletedAt": null

5. Object

A nested set of key-value pairs enclosed in curly braces. Objects can be nested to any depth, creating hierarchical data structures.

"address": {
  "city": "New York",
  "zip": "10001"
}

6. Array

An ordered list of values enclosed in square brackets. Arrays can contain any mix of JSON types - including other objects and arrays.

"scores": [95, 87, 92, 100]
"items": [{"id": 1}, {"id": 2}]
"mixed": [1, "hello", true, null]

JSON Syntax Rules

JSON has a small but strict set of syntax rules that trip up many beginners:

• Keys must be strings in double quotes - {"name": "Alice"} is valid, {name: "Alice"} is not
• Double quotes only - single quotes are not valid anywhere in JSON
• No trailing commas - {"a": 1, "b": 2,} is invalid JSON
• No comments - JSON does not support // comments or /* block comments */
• No undefined - JavaScript's undefined has no equivalent in JSON
• No functions - functions cannot be stored in JSON

Parsing and Stringifying JSON

Working with JSON in code means converting between JSON strings and native data structures. This is called parsing (string to object) and stringifying (object to string).

In JavaScript:

// Parse a JSON string into a JavaScript object
const jsonString = '{"name": "Alice", "age": 30}';
const obj = JSON.parse(jsonString);
console.log(obj.name); // "Alice"

// Stringify a JavaScript object into a JSON string
const user = { name: "Bob", age: 25 };
const str = JSON.stringify(user);
console.log(str); // '{"name":"Bob","age":25}'

// Pretty-print with indentation
const pretty = JSON.stringify(user, null, 2);
console.log(pretty);
// {
//   "name": "Bob",
//   "age": 25
// }

In Python:

import json

# Parse JSON string
json_string = '{"name": "Alice", "age": 30}'
data = json.loads(json_string)
print(data["name"])  # Alice

# Convert Python dict to JSON string
user = {"name": "Bob", "age": 25}
json_str = json.dumps(user)
print(json_str)  # {"name": "Bob", "age": 25}

# Pretty-print
pretty = json.dumps(user, indent=2)

# Read from file
with open("data.json", "r") as f:
    data = json.load(f)

# Write to file
with open("output.json", "w") as f:
    json.dump(user, f, indent=2)

JSON vs XML: Why JSON Won

Before JSON, XML was the dominant data exchange format for web services (SOAP APIs used XML extensively). JSON replaced it in most use cases because of several key advantages:

• Less verbose - the same data takes significantly fewer characters in JSON than XML
• Easier to read - the syntax is closer to how programmers already think about data
• Native JavaScript support - browsers can parse JSON directly without additional libraries
• Smaller payloads - less data transferred means faster API responses
• Simpler to parse - most languages have JSON support built in

Here is the same data in both formats to illustrate the difference:

// JSON (56 characters)
{"user": {"name": "Alice", "age": 30}}

// XML (equivalent, 67+ characters)
<user><name>Alice</name><age>30</age></user>

Where JSON is Used

JSON appears throughout modern software development in many different contexts:

• REST APIs - the universal format for request bodies and response payloads
• Configuration files - package.json in Node.js, tsconfig.json in TypeScript, settings.json in VS Code
• NoSQL databases - MongoDB stores documents as BSON (Binary JSON), Firebase uses JSON natively, PostgreSQL has JSONB column type
• Browser storage - localStorage and sessionStorage store data as JSON strings
• Structured logging - tools like Logstash and Splunk ingest JSON logs
• Data serialisation - sending objects between microservices
• GraphQL - all GraphQL responses are JSON
• Webhook payloads - event-driven systems send JSON payloads to subscribed endpoints

What JSON Cannot Represent - and What Happens When You Try

The six data types are the whole of JSON. Every language has values that do not fit, and each language's JSON library decides for itself what to do with them. Those decisions are where JSON stops being perfectly interchangeable. I ran each case below through Node.js 24 (JSON.parse / JSON.stringify) and Python 3.12 (json.loads / json.dumps) and recorded exactly what came back:

Three of these cause real bugs between services:

• Large IDs. JavaScript numbers are 64-bit floats, exact only up to 2⁵³ (9,007,199,254,740,991). A Python or Java service can happily send a 64-bit database ID above that, and a JavaScript client will round it to a different, valid-looking ID with no error. This is why many APIs, including Twitter's (now X's), send IDs as strings as well as numbers. If you control the API, send large IDs as strings.
• NaN from Python. By default, json.dumps writes NaN for a float that is not a number - a pandas column with a missing value is the classic source. Python reads it back fine, so the round trip looks healthy, but a JavaScript client's JSON.parse throws on the whole response. Pass allow_nan=False to make Python raise instead (ValueError: Out of range float values are not JSON compliant), and convert missing values to None first.
• Duplicate keys. The JSON specification says names should be unique, not that they must, and both libraries quietly keep the last value. If two layers of a system parse the same document with different libraries, they can disagree about which value is real - a known source of security bugs when one layer validates and another acts.

The pattern is the same each time: JSON the format is simple, but the mapping between JSON and each language is a set of choices. When data crosses a language boundary, test with the awkward values, not just the happy path.

Common JSON Mistakes to Avoid

Even experienced developers make these errors when writing JSON manually:

• Using single quotes instead of double quotes for strings or keys
• Leaving a trailing comma after the last item in an object or array
• Trying to add comments to a JSON file
• Using undefined as a value (it gets stripped by JSON.stringify)
• Storing dates as Date objects instead of ISO 8601 strings like "2024-01-15T09:30:00Z"

Validating JSON

When a JSON string fails to parse, it usually means there is a syntax error. You can validate JSON quickly using:

• Browser console - paste JSON.parse('your json here') and check for errors
• Online validators - many free tools will highlight exactly where your JSON is malformed
• Code editors - VS Code highlights JSON errors in .json files automatically