What Is JSON? Format, Syntax Rules, and Examples

JSON (JavaScript Object Notation) is a lightweight text format for structuring data as nested key-value pairs – the format almost every modern API, config file, and AI tool-calling system uses to pass information back and forth. It reads like a plain-language list of facts, which is exactly why both humans and machines parse it easily.

The JSON Format: Syntax Rules

JSON's syntax is deliberately small – a handful of rules cover the entire format:

• Six value types, nothing else. A JSON value is always one of: a string ("text"), a number (42 or 3.14, no separate integer/float types), a boolean (true/false), an array (an ordered list, [1, 2, 3]), an object (unordered key-value pairs, {"key": "value"}), or null (an explicit "no value," distinct from an empty string or zero).
• Keys and strings use double quotes only. Single quotes aren't valid JSON, even though they're common in JavaScript itself – {'key': 'value'} is not valid JSON, {"key": "value"} is.
• No trailing commas. [1, 2, 3,] is invalid; the comma after the last item breaks strict parsers, which is a common source of "unexpected token" errors when hand-editing a file.
• No comments. JSON has no // or /* */ syntax at all – Crockford removed comments from the spec deliberately (more on why below).
• Keys are always strings. Even numeric-looking keys ({"1": "first"}) are quoted strings, never bare numbers.

A .json file uses that extension and is served over the web with the MIME type application/json.

A JSON Object, in Practice

{
  "name": "Alex Rivera",
  "age": 34,
  "is_active": true,
  "middle_name": null,
  "labels": ["billing", "urgent"],
  "address": {
    "city": "Austin",
    "zip": "78701"
  }
}

This one example shows all six value types at once: a string (name), a number (age), a boolean (is_active), null (middle_name, meaning the field exists but has no value), a JSON array (labels), and a nested object (address). That's the entire vocabulary of the format – everything else is just these six types nested inside each other.

Reading and Writing JSON in Code

In JavaScript, two built-in functions handle the whole conversion between a JSON string and a usable object:

const jsonString = '{"name": "Alex", "age": 34}';

// String → object
const data = JSON.parse(jsonString);
console.log(data.name); // "Alex"

// Object → string
const backToString = JSON.stringify(data);

JSON.parse() takes a JSON-formatted string (say, an API response) and turns it into a real JavaScript object you can work with – data.name, data.age, and so on. JSON.stringify() does the reverse: it takes an object in memory and turns it into a JSON string, ready to send over the network or save to a file. Every other language has an equivalent pair (Python's json.loads()/json.dumps(), for example) – the format is the same, only the function names differ.

A Short History

JSON wasn't designed by a committee first and adopted later – it was noticed. Douglas Crockford specified and popularized it in the early 2000s as a lightweight alternative to XML for JavaScript applications, describing it as a subset of the object literal syntax already built into the JavaScript language – which is exactly why it needed no new parser to catch on. It became a formal standard later: RFC 8259 (IETF, 2017) and ECMA-404 (Ecma International) both define the same format, so "JSON" today means one precise, standardized thing rather than a loose convention.

JSON vs. XML

The "no comments" row has a specific story behind it: Crockford has explained that he removed comments from JSON on purpose, because he saw them being misused by some parsers as processing directives – which would have broken interoperability between different JSON implementations. The trade-off was intentional: a stricter, more uniform format over a more convenient one.

Where JSON Shows Up

JSON isn't tied to any one kind of software – it's the default shape for structured data almost everywhere:

• Config files. package.json, tsconfig.json, VS Code settings – JSON is the default format for project configuration across most modern tooling, because it's easy to diff, easy to validate, and every language can parse it.
• Mobile and web app state. A shopping cart, a user's saved preferences, a game's leaderboard – all typically travel between a client and a server as JSON, whether it's cached locally or synced through an API.
• IoT and sensor data. A smart thermostat or a fleet-tracking device often reports its readings as small JSON payloads – not because JSON is especially compact (formats like CBOR and Protocol Buffers are built specifically to be smaller and faster to parse), but because it's small enough for constrained devices while staying human-readable for debugging.
• AI tool-calling. When a model calls a tool – a search, a calculator, a database query – the function arguments and the result are JSON, because a JSON schema is simple enough for a model to generate reliably and simple enough for code to validate before acting on it.

Why This Matters for AI Agent Email

One specific corner of that last case is worth calling out: an AI email agent calling an email API built for agents lives or dies on how clean that JSON comes back. A good API returns already-parsed fields – subject, from, body, threadId – instead of raw MIME text the agent has to decode itself. Atomic Mail Agentic returns structured JSON for every mail operation for this reason – an agent gets real fields to reason over immediately, not a raw message to parse first.

FAQ

Is JSON only for web development? No – it's used for config files, logs, data storage, and increasingly as the default format AI systems use to talk to tools and APIs of any kind.

What's the difference between JSON and a JavaScript object? A JavaScript object is a live structure in running code; JSON is its text representation – a string format for storing or sending that same shape of data, usable from any language via JSON.parse()/JSON.stringify() or their equivalents, not just JavaScript.

What is the difference between JSON and XML? JSON uses key-value pairs with native data types and less markup; XML uses nested tags where every value is text, with a more mature schema-validation ecosystem. JSON is generally smaller and easier to parse; XML supports comments and has stronger tooling for document-style data.

Is JSON the same as SQL? No – they solve different problems entirely. SQL is a language for querying and managing data inside a relational database; JSON is a data format for structuring and exchanging data between systems. A database can store JSON documents, and a SQL query can even return results formatted as JSON, but one is a query language and the other is a data format.

Which is better, HTML or JSON? They're not interchangeable, so "better" depends on the job: HTML structures content for a web page a human reads in a browser; JSON structures data for two programs to exchange without any visual rendering involved. A weather app's data comes as JSON; the page displaying it is HTML.

Is JSON a coding language? No – JSON is a data format, not a programming language. It has no functions, loops, or logic of its own; it only describes data, which is then read and acted on by code written in an actual programming language.

Why did JSON largely replace XML for APIs? Less markup for the same data, native parsing in every major language, and a syntax simple enough that both humans and language models produce it correctly without heavy tooling.

Does the email API I use actually matter if it all returns JSON eventually? Yes – whether an API returns already-structured JSON or a raw message a client has to parse is the difference between an agent acting in one step and an agent (or a developer) writing a parsing layer first.

‍