If you interact with any API, work on any web application, or read any configuration file, you're working with JSON. It's the most widely used data interchange format in software development today — and for good reason. It's human-readable, lightweight, and natively supported by virtually every programming language. This guide explains JSON from first principles, with real examples and the common mistakes that trip up beginners.
What Is JSON and Where Did It Come From?
JSON stands for JavaScript Object Notation. It was formalized by Douglas Crockford in the early 2000s as a lightweight alternative to XML for transmitting data between a browser and a server. Despite its JavaScript origins, JSON is language-independent — there are JSON parsers and serializers for Python, Java, Ruby, Go, Rust, PHP, C#, and every other mainstream language.
JSON's rise to dominance is largely a story of simplicity winning out over complexity. XML was powerful but verbose. A simple key-value pair in XML required opening and closing tags: <name>Alice</name>. In JSON, the same data is "name": "Alice". Multiply this difference across thousands of fields in a large API response and the bandwidth and parsing overhead of XML becomes significant.
JSON Syntax: The Six Data Types
JSON supports exactly six data types — no more, no less. Understanding each one precisely prevents most beginner errors.
Strings
Strings are sequences of Unicode characters wrapped in double quotes — always double quotes, never single quotes. This is JSON's most common source of errors for developers who come from Python or JavaScript, where single quotes are acceptable.
Numbers
Numbers in JSON can be integers or floating-point values. No quotes required — a quoted number becomes a string, which behaves very differently in code.
Booleans
Boolean values are the lowercase literals true and false. They are not strings — "true" (with quotes) is a string, not a boolean.
Null
The null value represents an intentional absence of value. It is written as the lowercase literal null.
Objects
A JSON object is an unordered collection of key-value pairs enclosed in curly braces. Keys must be strings (in double quotes). Values can be any JSON type.
Arrays
An array is an ordered list of values enclosed in square brackets. Values can be any JSON type — including other objects or arrays, enabling deeply nested structures.
A Real-World Example: API Response
Here's what a typical REST API response looks like — for example, a request to a user profile endpoint:
Notice how objects nest inside objects, and how arrays and various data types are freely mixed. This is the power of JSON's flexible structure — it can represent arbitrarily complex hierarchical data in a format that any language can parse into its native data structures in one function call.
Common JSON Errors and How to Fix Them
Trailing Commas
One of the most frequent JSON mistakes is leaving a trailing comma after the last element in an array or object. JavaScript arrays allow this; JSON does not. This causes a parse error: {"name": "Alice", "age": 29,} — the comma after 29 is invalid.
Single Quotes
JSON requires double quotes for all strings, including keys. {'name': 'Alice'} is not valid JSON, even though it looks like a Python dictionary or a JavaScript object literal.
Comments
JSON does not support comments. Adding // this is a comment or /* block comment */ causes a parse error. If you need annotated configuration files, consider JSONC (JSON with Comments), YAML, or TOML instead.
Undefined Values
JavaScript has an undefined type, but JSON does not. If you try to serialize an object with undefined values to JSON in JavaScript, those keys will simply be omitted from the output — which can cause hard-to-debug data loss.
JSON vs. XML
XML was the dominant data exchange format before JSON. XML is more verbose but also more expressive — it supports attributes in addition to elements, namespaces for avoiding naming conflicts, and schemas for rigorous validation. For document-centric data (rich text with mixed content, publishing workflows, some financial EDI formats), XML still has advantages. For API responses, configuration files, and data serialization in modern web applications, JSON wins on simplicity, compactness, and parsing speed.
JSON in JavaScript and Python
In JavaScript, JSON.parse(str) converts a JSON string to a JavaScript object, and JSON.stringify(obj) converts an object to a JSON string. In Python, json.loads(str) parses JSON into a dictionary, and json.dumps(obj) serializes it. Both are standard library functions — no third-party packages needed for basic JSON handling.
Conclusion
JSON's success comes from a simple formula: it's just complex enough to represent any data structure while remaining simple enough for humans to read and write. Mastering the six data types, understanding the strict syntax rules (double quotes, no trailing commas, no comments), and having a reliable formatter for validation covers everything you'll need in day-to-day development. When an API response looks cryptic, a formatter is your first tool — not the last.