JSON Explained: The Data Format That Powers the Modern Web

JSON (JavaScript Object Notation) is the lingua franca of the modern web. Every time you load a web page, use a mobile app, or interact with an online service, JSON is likely flowing behind the scenes, carrying data between servers and clients. Despite its ubiquity, many developers and content creators use JSON without fully understanding its syntax, history, or best practices. This comprehensive guide explains what JSON is, why it replaced XML, how to read and write JSON correctly, common pitfalls to avoid, and best practices for working with JSON in modern web development.

What is JSON and where did it come from?

JSON was created by Douglas Crockford in the early 2000s as a lightweight data interchange format based on a subset of JavaScript. The specification was later standardized as ECMA-404 and RFC 8259. JSON's design goals were simplicity, human-readability, and machine-parseability. It achieved these goals so successfully that within a decade, it had largely replaced XML as the dominant data format for web APIs and configuration files.

JSON's popularity stems from its alignment with JavaScript, the programming language of the web. A JSON document is valid JavaScript syntax (with some historical exceptions), which means JavaScript can parse JSON natively using JSON.parse() without any external library. As web applications became more JavaScript-heavy with the rise of single-page applications (SPAs) and AJAX, JSON's native compatibility became a decisive advantage over XML, which required verbose parsing libraries.

JSON syntax: the complete reference

JSON has six data types and two structural elements. The structural elements are objects (enclosed in curly braces {}) and arrays (enclosed in square brackets []). Objects contain key-value pairs where keys are strings and values can be any JSON data type. Arrays are ordered lists of values. The six data types are string, number, boolean, null, object, and array.

Strings

JSON strings must be enclosed in double quotes. Single quotes are not valid JSON. Strings can contain any Unicode characters except control characters, which must be escaped. Common escape sequences include \" (double quote), \\ (backslash), \n (newline), \t (tab), \r (carriage return), and \uXXXX (Unicode character). For example, a string containing a quote: 'He said \"Hello\"'

Numbers

JSON numbers can be integers or floating-point, positive or negative. They cannot have leading zeros (except for the value 0 itself) and cannot include NaN (Not a Number) or Infinity, despite JavaScript supporting these. Scientific notation is supported: 1.5e3 means 1500. Numbers do not have quotes.

Booleans

JSON has two boolean values: true and false, written in lowercase without quotes. JavaScript's True, FALSE, or other capitalization variants are not valid JSON.

Null

JSON has a single null value, written in lowercase without quotes, representing the absence of a value. JavaScript's undefined is not valid JSON.

Objects

JSON objects are unordered collections of key-value pairs enclosed in curly braces. Keys must be strings (double-quoted) and must be unique within the object. Values can be any JSON data type, including nested objects and arrays. For example: {"name": "John", "age": 30, "active": true}

Arrays

JSON arrays are ordered lists of values enclosed in square brackets. Values can be any JSON data type, and arrays can contain mixed types (though this is often bad practice). Arrays can be nested. For example: [1, 2, 3, "four", true, null]

Why JSON replaced XML

In the late 1990s and early 2000s, XML (eXtensible Markup Language) was the dominant data format for web services. XML is verbose, requiring opening and closing tags for every element, and attributes for metadata. XML also required complex parsing (SAX, DOM, XPath) and had ambiguous data modeling (when to use elements vs attributes).

JSON addressed all of XML's weaknesses. JSON is more compact (no closing tags), simpler to parse (native JavaScript support, no parser libraries needed), has unambiguous data modeling (everything is either a key-value pair or an array element), and maps directly to data structures in most programming languages (objects/dictionaries/maps and arrays/lists). JSON also lacks XML's complexity around namespaces, schemas, and processing instructions, which added overhead without proportional benefit for most use cases.

The transition from XML to JSON happened gradually from 2005 to 2015 as web APIs shifted from SOAP (XML-based) to REST (typically JSON-based). Today, JSON is used by virtually all modern web APIs, configuration files (VS Code, package.json), NoSQL databases (MongoDB, CouchDB), message queues, and logging systems. XML remains in use for specific domains like document markup (DocBook, DITA), scientific data (CML, SBML), and legacy enterprise systems.

Common JSON use cases

Web APIs

REST APIs typically return JSON responses and accept JSON request bodies. JSON's compactness reduces bandwidth, its human-readability simplifies debugging, and its native JavaScript support enables direct use in web applications. GraphQL, the modern alternative to REST, also uses JSON for responses. Example: GET /api/users/123 might return {"id": 123, "name": "John Doe", "email": "john@example.com"}.

Configuration files

Many modern tools use JSON for configuration: package.json (Node.js), tsconfig.json (TypeScript), .eslintrc.json (ESLint), launch.json (VS Code), manifest.json (web apps). JSON's simplicity makes it ideal for human-edited configuration. However, JSON's lack of comments (a deliberate design choice) is a limitation for configuration files, leading to variants like JSONC (JSON with comments) and JSON5 (extended JSON with comments, trailing commas, and other relaxations).

NoSQL databases

Document-oriented NoSQL databases like MongoDB, CouchDB, and Amazon DocumentDB store data in JSON-like documents (technically BSON in MongoDB's case, but conceptually JSON). This allows flexible schemas where each document can have different fields, unlike relational databases where all rows must conform to the table schema.

Logging and data serialization

Structured logging formats like JSON Lines (one JSON object per line) enable efficient log parsing and analysis. JSON's universality means logs can be consumed by any programming language or tool. Data serialization for message queues (RabbitMQ, Kafka) often uses JSON for human-readable messages.

Browser storage

Web apps use localStorage and sessionStorage for client-side storage, which only stores strings. JSON is used to serialize JavaScript objects for storage and deserialize them when retrieved. Example: localStorage.setItem('user', JSON.stringify(user)) and JSON.parse(localStorage.getItem('user')).

Working with JSON in JavaScript

JavaScript provides two built-in functions for working with JSON: JSON.parse() converts a JSON string to a JavaScript object, and JSON.stringify() converts a JavaScript object to a JSON string. Both functions are available in all modern browsers and Node.js.

JSON.parse() accepts a JSON string and returns the corresponding JavaScript value. If the string is not valid JSON, it throws a SyntaxError. For security, always wrap JSON.parse() in a try-catch block when parsing untrusted input. JSON.parse() also accepts an optional reviver function that can transform each value during parsing.

JSON.stringify() accepts a JavaScript value and returns a JSON string. It accepts optional parameters: a replacer function or array that controls which values to include, and a space parameter for pretty-printing. JSON.stringify(obj, null, 2) produces 2-space indented JSON, which is useful for debugging. Note that JSON.stringify() omits functions, undefined, and Symbol values, and converts NaN, Infinity, and -Infinity to null.

Common JSON pitfalls and mistakes

Trailing commas

JSON does not allow trailing commas after the last item in an object or array. {"a": 1,} and [1, 2, 3,] are invalid JSON, though they are valid JavaScript. This is a common source of errors when hand-writing JSON or generating JSON from code. Most JSON validators flag trailing commas.

Single quotes

JSON requires double quotes for strings and keys. Single quotes are not valid JSON. {'name': 'John'} is invalid; {"name": "John"} is valid. This is a common mistake for developers coming from Python or Ruby where single quotes are common.

Unquoted keys

In JavaScript, object keys do not need quotes if they are valid identifiers: {name: "John"} works in JavaScript. But JSON requires all keys to be quoted: {"name": "John"}. This is a common mistake when writing JSON by hand.

Comments

Standard JSON does not support comments. Adding comments with // or /* */ will cause JSON.parse() to fail. For configuration files that need comments, use JSONC, JSON5, or YAML instead. Some tools like VS Code accept JSONC in their configuration files despite the .json extension.

Special characters in strings

Double quotes, backslashes, and control characters must be escaped in JSON strings. Forgetting to escape these causes parse errors. A common mistake is forgetting to escape backslashes in Windows file paths: "C:\\Users\\John" is valid; "C:\Users\John" is invalid (backslash-U and backslash-J are invalid escape sequences).

NaN, Infinity, and undefined

JSON does not support NaN, Infinity, -Infinity, or undefined. JSON.stringify() converts these to null. If you need to preserve these values, you must use a custom serialization format or a JSON extension like JSON5.

JSON validation and formatting

Validating JSON before using it prevents runtime errors. JSON validation checks that the syntax is correct (proper quotes, no trailing commas, valid escape sequences) and that the structure matches expectations (required fields, correct types). Tools like the sevi.fun JSON Formatter validate JSON syntax and provide clear error messages identifying the location of problems.

Formatting JSON (also called beautifying or pretty-printing) adds indentation and line breaks to make JSON readable by humans. Minified JSON (no whitespace) is smaller for transmission over networks. Use formatted JSON for development and debugging, minified JSON for production. The sevi.fun JSON Formatter handles both operations.

JSON Schema: validating structure

JSON Schema is a vocabulary for annotating and validating JSON documents. It allows you to define the expected structure of a JSON object: required fields, field types, value constraints (min, max, pattern), and nested object structures. JSON Schema is useful for API documentation, input validation, and automated testing.

For example, a schema might specify that a user object must have a name (string), age (integer, minimum 0), and email (string matching email pattern). Any JSON that does not conform to this schema fails validation. Tools like ajv (Another JSON Validator) implement JSON Schema validation in JavaScript.

Best practices for JSON in APIs

Use consistent naming conventions

Choose a naming convention for JSON keys and stick with it. Common conventions: camelCase (preferred for JavaScript/TypeScript APIs), snake_case (common in Python APIs), or kebab-case (rare in JSON). Mixing conventions within an API is confusing and error-prone.

Use proper HTTP status codes

When returning JSON from an API, use appropriate HTTP status codes: 200 for success, 201 for creation, 400 for bad request (invalid JSON, missing fields), 401 for unauthorized, 404 for not found, 500 for server error. Include a JSON error body with details: {"error": "Invalid email format", "field": "email"}.

Version your API

Include API version in the URL (/api/v1/users) or in a header (Accept: application/vnd.api+json;version=1). This allows you to make breaking changes without breaking existing clients. When you need to make a breaking change, release a new version (v2) and eventually deprecate the old version.

Use pagination for large lists

Do not return thousands of items in a single JSON response. Use pagination with limit and offset, or cursor-based pagination. Return metadata about the total count and next page URL: {"data": [...], "total": 1234, "next": "/api/users?offset=20&limit=20"}.

Include Content-Type header

Always set the Content-Type header to application/json for JSON responses. This allows clients to parse the response correctly. For JSON requests, clients should set Content-Type: application/json on their requests.

Conclusion

JSON is the dominant data format of the modern web, prized for its simplicity, human-readability, and native JavaScript support. Understanding JSON syntax, common pitfalls, and best practices is essential for anyone working with web APIs, configuration files, or data interchange. The sevi.fun JSON Formatter provides validation, beautification, and minification of JSON data, all running locally in your browser for maximum privacy. By following the best practices outlined in this guide, you can work with JSON effectively, avoid common mistakes, and build APIs and applications that are robust, maintainable, and interoperable with the broader web ecosystem.