JSON, Explained: The Data Format That Silently Runs the Web

In one sentence

JSON is a lightweight, text-based format for structuring and exchanging data that is easy for humans to read and for machines to parse.

The problem it solves

In the olden days of the web (the late '90s and early 2000s), if you wanted your website to fetch new data without a full page reload, you were likely using a technology called AJAX (Asynchronous JavaScript and XML). And as the name implies, the data format of choice was XML.

XML is powerful, but it's also... verbose. It's chunky. It's full of opening tags, closing tags, attributes, and namespaces. Parsing it in JavaScript, the language of the browser, was a chore. You had to navigate a clunky document tree, and it just didn't feel native.

<!-- This is just one user. Imagine a list of thousands. Yikes. -->
<user id="123">
  <username>coder_dave</username>
  <isActive>true</isActive>
  <roles>
    <role>admin</role>
    <role>editor</role>
  </roles>
</user>

Around 2001, a developer named Douglas Crockford was working on a project and needed a simpler way to pass data to the browser. He had a brilliant realization: JavaScript already had a perfectly good way to represent data structures—its own object literal syntax. What if you could just send data as a string that looked like a JavaScript object?

This was the birth of JSON (JavaScript Object Notation). A server could send this text:

{
  "id": 123,
  "username": "coder_dave",
  "isActive": true,
  "roles": ["admin", "editor"]
}

...and the browser could, with minimal effort, turn it into a native JavaScript object it could instantly work with. It was lean, clean, and perfectly suited to the web's native tongue. This simplicity caused a Cambrian explosion in web APIs, powering the rise of dynamic single-page applications, mobile backends, and basically the entire modern internet as we know it. JSON didn't just solve a technical problem; it greased the wheels for a whole new generation of software.

How it works under the hood

At its core, JSON is just a set of rules for writing down data as text. The rules are simple, which is precisely why it's so successful.

The Building Blocks: Keys and Values

The entire universe of JSON is built on one simple structure: the key-value pair.

"key": value

• The key is always a string, enclosed in double quotes. This is non-negotiable.
• The value can be one of a few specific data types.

This pairing describes a single piece of information, like "name": "Luke Skywalker" or "age": 19.

The Data Types

JSON is strict about its value types. You can't just throw anything in there. You get six basic types plus null.

Type	Example	Description
String	"The force is strong with this one."	Any text. Must be in double quotes.
Number	1138 or 3.14	Integers or floating-point numbers. No distinction.
Boolean	true or false	Always lowercase. Represents a binary state.
Array	["Tatooine", "Dagobah", "Bespin"]	An ordered list of values, enclosed in [].
Object	{ "weapon": "lightsaber", "color": "green" }	An unordered collection of key-value pairs, enclosed in {}.
Null	null	Represents the intentional absence of a value.

That's it. Notice what's missing: functions, dates (they're sent as strings), undefined, and, most famously, comments. This minimalism is a feature, not a bug; it keeps the format unambiguous and easy for any programming language to parse.

Structuring Data: Objects and Arrays

The real power comes from nesting these types. The value in a key-value pair can be another object or an array. This lets you build up arbitrarily complex data structures.

Objects ({...}) are used to group related data about a single "thing." Think of it as a dictionary entry or a profile.

Arrays ([...]) are used for ordered lists of items. The items in an array can be of any type, even mixed (though it's usually good practice to keep them uniform).

Let's look at a more complete example:

{
  "squadName": "Star Wars Heroes",
  "formed": 1977,
  "active": true,
  "members": [
    {
      "name": "Luke Skywalker",
      "age": 19,
      "secretIdentity": null,
      "powers": [
        "Jedi mind tricks",
        "Piloting",
        "The Force"
      ]
    },
    {
      "name": "Han Solo",
      "age": 29,
      "secretIdentity": null,
      "powers": [
        "Blaster accuracy",
        "Sarcasm",
        "Kessel Run under 12 parsecs"
      ]
    }
  ]
}

See? We have an outer object describing the squad. One of its properties, "members", is an array. Each element of that array is another object, representing a single hero. And each hero object has its own properties, one of which ("powers") is another array of strings. This is how you build a data tree with JSON.

From Text to Object: Parsing

The magic trick is turning this text into something a program can use.

1. Serialization: A server-side application (written in Python, Java, Go, etc.) has data in memory. It uses a JSON library to serialize that data into a JSON-formatted string. In JavaScript, this is JSON.stringify().
2. Transmission: This string is sent over the network, typically as the body of an HTTP response.
3. Parsing: The client (like a web browser) receives this string. It uses a built-in JSON parser to turn the string back into a native data structure it can manipulate. In JavaScript, this is JSON.parse().

This two-step process of stringify-and-parse is the heartbeat of modern web communication.

Real-world stories

The Buggy Mobile App

A startup launched a mobile ordering app for a local restaurant chain. One morning, the app started crashing for every single user upon opening. The dev team was in full-blown panic mode. The server logs showed the API was sending a 200 OK status, and the data looked fine when they quickly glanced at it. After hours of frantic debugging, they finally inspected the raw text of the API response. A backend developer, trying to be helpful, had added a note for his colleagues directly in the code that generated the JSON: // TODO: Confirm weekend hours. This comment was being included in the final JSON string. While harmless in code, a comment makes JSON invalid. The app's strict JSON parser saw the unexpected // and immediately failed, crashing the app before it could even display an error message.

Lesson: JSON parsers are not forgiving. The format is strictly defined for a reason: to guarantee interoperability. A single invalid character—a comment, a trailing comma, a single quote—will cause a valid parser to reject the entire payload.

The International Pricing Fiasco

An American e-commerce company was expanding to Germany. Their API sent product info as JSON, including a price field. For a $19.95 item, the JSON was "price": 19.95. In preparation for the German launch, a developer updated the backend to format the price according to German conventions, where the comma is a decimal separator. The API started sending "price": "19,95". The frontend code, however, was still expecting a number. In JavaScript, parseFloat("19,95") evaluates to just 19, dropping everything after the comma. Suddenly, all products in Germany were being displayed at a massive, incorrect discount.

Lesson: JSON is for raw data, not for presentation. The data type matters. A price is a number, so send it as a number (19.95). Let the client-side application (the browser or mobile app) handle the job of formatting that number into $19.95 or 19,95 € or ¥19 based on the user's locale. Don't mix data and display logic.

The Config File That Couldn't Be Explained

A small team was setting up a new service using a config.json file to store database connection strings, API keys, and feature flags. As the configuration grew more complex, they desperately needed to add comments to explain what each cryptic setting did and why it was set to a particular value. But JSON forbids comments. Their "solution" was to create a config_documentation.md file that had to be kept in sync with config.json. This quickly became a huge pain. Eventually, they realized their mistake.

Lesson: Use the right tool for the job. JSON is the undisputed champion for data interchange between machines (like an API response). But for human-maintained configuration files where comments and readability are critical, other formats like YAML or even a simple .js file are often a much better choice.

Common mistakes and traps

• Trailing Commas: Adding a comma after the last element in an object or array ("key": "value",}) will make your JSON invalid. This is a common error for developers used to more forgiving syntaxes in JavaScript.
• Comments: You can't have them. // and /* ... */ are not part of the spec and will break parsing. If you need to add metadata, you have to do it within the data structure itself, e.g., { "_comment": "This is my note", "realData": "..." }.
• Single Quotes: All keys and all string values must use double quotes ("). Using single quotes (') is invalid JSON, even though it's common in JavaScript.
• Undefined Keys: Sending {"key": undefined} is not possible. The key-value pair will typically be omitted during serialization. To represent a missing value, use null.
• Using Numbers as Strings: While you can send a number as a string (e.g., "id": "123"), it's bad practice. It forces the receiving application to do extra work to convert it back to a number and can lead to subtle bugs (e.g., "10" > "9" is false in string comparison).

Why it belongs on your radar

If you touch code in any capacity, you'll encounter JSON. It's not a question of if, but when and how often.

• Web Developers: You'll consume JSON from APIs and send it from your forms. Your entire application state is likely managed as a JSON-like object.
• Backend Developers: You'll build APIs that produce JSON and consume JSON from other services.
• Mobile Developers: You'll communicate with your backend exclusively via APIs that speak JSON.
• DevOps/SREs: Infrastructure-as-code tools, CI/CD pipelines, and cloud provider APIs are all configured and managed with JSON or similar formats.
• Data Scientists: You'll pull data from web APIs, and it will almost always arrive as JSON.
• Curious Non-Developers: Understanding the simple key-value structure of JSON can demystify how apps on your phone get their data and how websites load content dynamically. It's a peek under the hood of the digital world.

JSON is the lingua franca of data on the internet. Knowing its rules and its purpose is a fundamental skill for anyone building or working with modern software.

Go deeper

• JSON.org: The original, one-page spec by Douglas Crockford. A masterclass in simplicity.
• RFC 8259: The official IETF "standard" that formalizes the JSON format for the internet.
• MDN: Working with JSON: The definitive guide for JavaScript developers, explaining JSON.parse() and JSON.stringify().
• Wikipedia: JSON: Provides a great overview of the history, derivatives (like GeoJSON), and comparisons to other formats.