JSON Explained: Everything Developers Need to Know

Published on October 18, 2025 · 12 min read

JSON -- JavaScript Object Notation -- is the lingua franca of modern software. It is how your frontend talks to your backend, how APIs deliver data across the internet, how configuration files store settings, and how databases like MongoDB store documents. If you write code in any language, you work with JSON daily, whether you realize it or not.

Yet despite its simplicity, JSON is a constant source of bugs. A missing comma, a trailing comma, a single quote instead of a double quote, an unescaped newline in a string -- these tiny mistakes produce cryptic parse errors that can waste hours of debugging time. This guide covers JSON thoroughly: from the basic syntax to advanced validation patterns, from the most common mistakes to the best practices that prevent them.

What Is JSON and Why Does It Matter?

JSON was formalized by Douglas Crockford in the early 2000s as a lightweight alternative to XML for data interchange. It is a subset of JavaScript object literal syntax, which means any valid JSON is also valid JavaScript -- but the reverse is not true, and that distinction is the source of many common errors.

Why JSON Won

JSON succeeded because of three qualities:

• Human readability. Unlike binary formats, you can open a JSON file in any text editor and understand its structure immediately. This makes debugging and manual inspection straightforward.
• Machine simplicity. The JSON grammar fits on a single page. Parsers are small, fast, and available in every programming language. There are no edge cases around processing instructions, namespaces, or DTDs (all of which complicate XML).
• Universal support. Every modern programming language includes a JSON parser in its standard library. JavaScript has JSON.parse() and JSON.stringify(), Python has the json module, Go has encoding/json, and so on. This ubiquity makes JSON the default choice for any data interchange scenario.

Today, JSON is specified by two standards: ECMA-404 (which defines the syntax) and RFC 8259 (which defines the interchange format with stricter requirements around encoding and handling). For practical purposes, they describe the same thing.

JSON Syntax Rules

JSON's syntax is minimal, which is its greatest strength and also why small violations cause immediate failures. There is no error recovery in JSON parsing -- a single syntax error makes the entire document invalid.

The Two Root Structures

A valid JSON document must have exactly one root value, which is typically either an object (enclosed in curly braces) or an array (enclosed in square brackets). Technically, RFC 8259 allows any JSON value as the root -- a standalone string, number, boolean, or null is valid JSON -- but in practice, APIs and configuration files almost always use an object or array.

Objects

A JSON object is an unordered collection of key-value pairs. Keys must be strings enclosed in double quotes. Values can be any JSON data type. Pairs are separated by commas, and there must be no trailing comma after the last pair.

{
  "name": "Alice Chen",
  "age": 32,
  "isActive": true,
  "address": {
    "street": "742 Evergreen Terrace",
    "city": "Springfield"
  },
  "tags": ["developer", "speaker"]
}

Arrays

A JSON array is an ordered list of values. Values can be of mixed types (though in practice they rarely are). Elements are separated by commas with no trailing comma allowed.

[
  {"id": 1, "status": "active"},
  {"id": 2, "status": "pending"},
  {"id": 3, "status": "closed"}
]

Whitespace

JSON is whitespace-insensitive between tokens. Spaces, tabs, newlines, and carriage returns are all allowed and ignored by parsers. The compact form {"a":1,"b":2} and the pretty-printed form with indentation are semantically identical. Use minified JSON for network transfer (smaller payload) and pretty-printed JSON for files humans need to read.

The Six JSON Data Types

JSON supports exactly six data types. Understanding their constraints prevents a large class of common errors.

1. String

A sequence of Unicode characters enclosed in double quotes. Single quotes are not valid JSON. Certain characters must be escaped with a backslash: double quote (\"), backslash (\\), newline (\n), tab (\t), carriage return (\r), form feed (\f), and backspace (\b). Arbitrary Unicode characters can be escaped as \uXXXX.

2. Number

JSON numbers can be integers or floating-point, positive or negative. They may use exponential notation (e.g., 1.5e10). However, JSON does not support several number formats that many programming languages allow: no leading zeros (except for 0 itself), no hexadecimal (0xFF), no octal, no Infinity, no NaN, and no trailing decimal point (5. is invalid; use 5.0).

3. Boolean

Either true or false, always lowercase. True, TRUE, yes, 1 -- none of these are valid JSON booleans.

4. Null

The literal null, always lowercase. It represents the intentional absence of a value. Null, NULL, None, and undefined are not valid.

5. Object

As described above: a collection of key-value pairs in curly braces. Keys must be unique within each object (the spec says parsers "should" reject duplicates, and behavior with duplicate keys is implementation-defined -- some parsers take the last value, some take the first, and some reject entirely).

6. Array

An ordered sequence of values in square brackets. Arrays can be empty ([]), and they can contain mixed types, though uniform types are the convention.

Notably absent: dates, comments, binary data, and undefined. Dates are typically represented as ISO 8601 strings ("2026-04-16T09:30:00Z"). Comments are not supported at all -- this is intentional, as JSON is a data interchange format, not a configuration language. Binary data must be Base64-encoded into a string. And undefined is a JavaScript concept that has no JSON equivalent.

Common JSON Errors and How to Fix Them

JSON parsers produce notoriously unhelpful error messages. Knowing the common mistakes lets you spot the problem before the parser's vague complaint sends you on a wild goose chase.

Trailing Commas

The single most common JSON error. JavaScript allows trailing commas in objects and arrays; JSON does not. After copying data from JavaScript code, the last item's trailing comma will break the parser.

// INVALID -- trailing comma after "blue"
{"colors": ["red", "green", "blue",]}

// VALID
{"colors": ["red", "green", "blue"]}

Single Quotes

JSON requires double quotes for both keys and string values. Python developers frequently hit this when using str() on a dictionary, which produces single-quoted output that is valid Python but invalid JSON. Always use json.dumps() instead.

Unquoted Keys

JavaScript allows unquoted object keys; JSON does not. Every key must be a double-quoted string.

// INVALID
{name: "Alice", age: 32}

// VALID
{"name": "Alice", "age": 32}

Unescaped Special Characters

Literal newlines, tabs, and backslashes inside strings must be escaped. A multiline string pasted directly into a JSON value will break parsing. Use \n for newlines and \\ for literal backslashes.

Numbers with Leading Zeros

007 is not valid JSON. Use 7 instead. If you need to preserve leading zeros (like zip codes or phone numbers), store them as strings.

Comments

No form of comment is valid in JSON. Not //, not /* */, not #. If you need comments in a configuration file, consider using JSONC (JSON with Comments, supported by VS Code), JSON5, or YAML instead.

JSON and APIs

JSON dominates API communication. Understanding how it flows through the request-response cycle helps you build more robust integrations.

Request Bodies

When sending JSON in an HTTP request, set the Content-Type header to application/json. This tells the server how to parse the body. Omitting this header is a frequent cause of "invalid request" errors -- the server may try to parse your JSON as form data or plain text.

Response Handling

Always validate and handle API responses defensively. Do not assume the structure will match the documentation. Common issues include:

• Null values where you expect objects. An API might return {"user": null} instead of omitting the field entirely.
• Numbers as strings. Some APIs return IDs, timestamps, or monetary values as strings to avoid floating-point precision issues. Always check the actual type.
• Additional or missing fields. APIs evolve over time. Your code should ignore unknown fields gracefully and handle missing optional fields with sensible defaults.
• Large numbers. JSON numbers have no size limit in the spec, but JavaScript's Number type loses precision for integers beyond 2^53. If an API returns large IDs (common with Snowflake IDs), they may need to be handled as strings.

Pagination Patterns

APIs that return collections almost always paginate. The two common JSON patterns are offset-based (including a "total" count and "offset" parameter) and cursor-based (including a "next_cursor" or "next_page_token" field). Cursor-based pagination is more efficient for large datasets and does not suffer from drift when items are added or removed between pages.

Validation and Schema

Syntax validation (is this valid JSON?) is just the first step. Structural validation (does this JSON have the shape my code expects?) is where JSON Schema comes in.

JSON Schema

JSON Schema is a specification for describing the structure of JSON data. It lets you define which fields are required, what types they should be, valid value ranges, string patterns, and relationships between fields. A schema acts as a contract between the data producer and consumer.

Key schema features include:

• Type constraints -- specify that a field must be a string, number, array, or object.
• Required fields -- list which properties must be present.
• Value constraints -- minimum/maximum for numbers, minLength/maxLength for strings, enum for a fixed set of allowed values, pattern for regex matching.
• Nested schemas -- define the structure of objects within objects and the items within arrays.
• Conditional schemas -- using if/then/else to apply different validation rules based on the value of another field.

Where to Validate

Validate at every trust boundary. Specifically:

• API endpoints: validate incoming request bodies before processing. This catches malformed data before it can cause errors deeper in your logic or corrupt your database.
• Configuration loading: validate config files at startup. A typo in a config value should produce a clear error message on launch, not a mysterious failure at 3 AM.
• Third-party data: validate responses from external APIs, even ones you trust. Services change their response formats, sometimes without warning.

JSON vs. YAML vs. XML vs. CSV

JSON is excellent for structured data interchange, but it is not the best choice for every situation. Understanding the alternatives helps you pick the right format.

YAML

YAML is a superset of JSON (any valid JSON is valid YAML) that adds human-friendly features: comments, multiline strings, anchors and aliases for reuse, and indentation-based nesting instead of braces. YAML is the dominant format for configuration files (Docker Compose, Kubernetes, CI/CD pipelines) because those files are primarily maintained by humans. The downsides: YAML's whitespace sensitivity makes it error-prone for machine generation, and the specification is extremely complex (the YAML 1.2 spec is over 80 pages).

XML

XML was the standard data interchange format before JSON. It supports namespaces, schemas (XSD), transformations (XSLT), and has mature tooling. XML is still prevalent in enterprise systems, SOAP APIs, and document formats (DOCX, SVG, and HTML are all XML-based). The main drawback is verbosity -- XML represents the same data in roughly twice the bytes as JSON, and parsing is significantly slower.

CSV

CSV (Comma-Separated Values) is the simplest tabular data format: rows of fields separated by commas. It is excellent for flat, tabular data (spreadsheet exports, database dumps, log files) and can be processed line by line without loading the entire file into memory. CSV cannot represent nested or hierarchical data, has no type information (everything is a string), and has surprisingly many edge cases around quoting, escaping, and encoding that make reliable parsing harder than it first appears.

When to Use What

• JSON: API communication, data interchange between services, document databases, configuration files read by applications.
• YAML: Configuration files maintained by humans, especially in DevOps contexts. Use when comments are needed.
• XML: Legacy system integration, document formats requiring mixed content, scenarios needing schema validation with XSD.
• CSV: Tabular data exchange, spreadsheet import/export, data science pipelines, log files.

Best Practices for Production JSON

Following these practices prevents the majority of JSON-related bugs and maintenance headaches in production systems.

Use Consistent Naming Conventions

Pick one style and enforce it everywhere. camelCase is the JavaScript convention and the most common in web APIs. snake_case is standard in Python and Ruby ecosystems. kebab-case is occasionally used but less common. The worst outcome is mixing conventions within the same API -- userName next to email_address next to phone-number is a maintenance nightmare.

Handle Null Intentionally

Decide whether an absent field and a field with a null value mean the same thing in your system. In many APIs, omitting a field in a PATCH request means "do not change this" while sending null means "clear this value." Document and enforce this distinction.

Use Strings for IDs and Money

Numeric IDs that exceed 2^53 will lose precision in JavaScript. Monetary values stored as floating-point numbers accumulate rounding errors (0.1 + 0.2 !== 0.3). Represent both as strings to guarantee precision across all consumers. For money, include the currency code and use the smallest unit (cents, not dollars): {"amount": "1599", "currency": "USD"}.

Use ISO 8601 for Dates

Always represent dates and times as ISO 8601 strings with timezone information: "2026-04-16T14:30:00Z". Never use Unix timestamps in JSON meant for human-facing systems -- they are unreadable and timezone-ambiguous. Never use locale-specific formats like "04/16/2026" which are ambiguous between American and European conventions.

Version Your API Responses

Include a version field or use URL versioning so that changes to your JSON structure do not break existing consumers. Adding new fields is generally safe; renaming or removing fields requires a new version.

Keep Payloads Lean

Only include data the consumer actually needs. Sending a user's entire profile when the client only needs their name and avatar URL wastes bandwidth, increases parse time, and may leak sensitive information. Offer field selection parameters or create purpose-specific endpoints.

Provide Meaningful Error Responses

When validation fails, return a structured JSON error response that tells the consumer exactly what went wrong and where. Include the field path, the constraint that was violated, and a human-readable message. A response like {"errors": [{"field": "email", "code": "invalid_format", "message": "Must be a valid email address"}]} is infinitely more useful than {"error": "Bad Request"}.

JSON's simplicity is deceptive. The format is easy to learn but requires discipline to use well in production systems. By understanding the specification precisely, validating at trust boundaries, choosing appropriate types, and following consistent conventions, you eliminate entire categories of bugs and build APIs that are a pleasure to work with.