← Back to Blog

What Is JSON? A Plain-English Guide for Beginners

I spend a fair amount of time debugging malformed JSON while maintaining the tools on this site — these are the syntax mistakes I see most often.

JSON — JavaScript Object Notation — is the lingua franca of modern software. It is how your browser and web server communicate, how mobile apps fetch data, how configuration files store settings, and how APIs exchange information across the internet. Despite being everywhere, many developers and non-developers encounter JSON without a clear mental model of its rules. This guide gives you that mental model.

What Is JSON?

JSON is a lightweight, human-readable text format for representing structured data. It was created by Douglas Crockford in the early 2000s, derived from JavaScript object literal syntax, but is now language-independent — parseable by virtually every programming language. JSON replaced XML as the dominant data interchange format for web APIs because it is simpler, more compact, and easier for both humans and machines to read.

A JSON document is either a single value, object, or array — and those can be nested inside each other to any depth needed to represent complex data.

The Six JSON Data Types

Type	Example	Notes
String	"Hello, World!"	Always double quotes. Never single quotes.
Number	42, 3.14, -7, 1.2e10	No distinction between integer and float.
Boolean	true, false	Lowercase only.
Null	null	Represents absence of value. Lowercase.
Object	{"key": "value"}	Unordered key-value pairs. Keys must be strings.
Array	[1, "two", true]	Ordered list. Can mix types.

JSON Syntax Rules (The Complete List)

1. Strings must use double quotes. "name" is valid; 'name' is not.
2. Object keys must be strings. {"age": 30} is valid; {age: 30} is not.
3. No trailing commas. [1, 2, 3,] is invalid JSON (though JavaScript allows it).
4. No comments. JSON has no comment syntax. // comment or /* comment */ both cause parse errors.
5. No undefined. JavaScript's undefined is not a JSON type. Use null instead.
6. Numbers cannot have leading zeros. 007 is invalid; 7 is valid.
7. Infinity and NaN are not valid JSON values. Use null or a string representation instead.
8. Encoding must be Unicode. JSON is always UTF-8, UTF-16, or UTF-32 (UTF-8 is standard).

A Real-World JSON Example

Here is a JSON object representing a user profile from an API response:

{
  "id": "usr_9f3k2m",
  "name": "Zahoor Ahmad",
  "email": "zahoor@example.com",
  "age": 28,
  "isVerified": true,
  "address": {
    "city": "Srinagar",
    "state": "Jammu & Kashmir",
    "pincode": "190001"
  },
  "tags": ["researcher", "developer", "writer"],
  "avatar": null,
  "createdAt": 1700000000
}

Beautify vs Minify: When to Use Each

Beautified (pretty-printed) JSON uses indentation and newlines for human readability. Use it during development, debugging, and in configuration files that humans read and edit. The extra whitespace carries no semantic meaning — a JSON parser treats both forms identically.

Minified JSON removes all unnecessary whitespace, reducing file size. A large API response that is 50KB beautified may compress to 35KB minified. Use it in production API responses to reduce bandwidth and improve load time. Most web servers also apply gzip compression on top, reducing size further.

JSON vs XML: Why JSON Won

Feature	JSON	XML
Verbosity	Compact	Very verbose (opening and closing tags)
Readability	Easy for humans	Harder to read with deep nesting
Native in JavaScript	Yes (JSON.parse, JSON.stringify)	Requires DOMParser
Comments	No	Yes (<!-- -->)
Schema validation	JSON Schema	XSD (powerful but complex)
Binary support	Not native (use Base64)	Not native
Dominant use	REST APIs, config, NoSQL	SOAP, enterprise, document formats

JSON in Different Contexts

REST APIs

The vast majority of REST APIs send and receive JSON. When a React app fetches your user data from a backend, both the request body (POST/PUT) and response body are JSON. The Content-Type header is application/json.

Configuration Files

package.json in Node.js, tsconfig.json in TypeScript, settings.json in VS Code, and manifest.json in browser extensions are all JSON. The lack of comment support frustrates many developers — which is why JSONC (JSON with Comments) and JSON5 exist as supersets for configuration use cases.

NoSQL Databases

MongoDB stores documents in BSON (Binary JSON), a binary extension of JSON. Firebase Realtime Database and Firestore store data as JSON trees. Elasticsearch indexes JSON documents.

Parsing JSON in Major Programming Languages

Every major language includes JSON support either natively or in its standard library.

JavaScript / Node.js

JSON.parse(string) converts a JSON string to a JavaScript object. JSON.stringify(object) converts in the other direction. For pretty output: JSON.stringify(obj, null, 2) produces two-space indentation. Common pitfall: passing undefined values or circular object references to stringify will throw a TypeError — check your object structure first.

Python

The built-in json module: json.loads(string) parses JSON to a Python dict; json.dumps(obj, indent=2) serialises with pretty-printing. Python's None maps to JSON null; Python True/False map to lowercase JSON true/false. For large files, use json.load(file_object) instead of reading the whole file into a string first.

Java

Java's standard library lacks JSON support — use Jackson or Gson. Jackson is the industry standard: ObjectMapper.readValue(json, MyClass.class) to parse into a typed Java object; objectMapper.writeValueAsString(obj) to serialise. Jackson's databind module handles complex type mappings including generics and nested objects.

JSON Schema: Validating Structure Programmatically

JSON Schema is a vocabulary for describing and validating JSON data structure. It lets you specify exactly what fields a JSON object must have, the type of each field, which fields are required, and constraints like minimum/maximum values or string regex patterns. This is used by REST API documentation tools (OpenAPI/Swagger), configuration validators (GitHub Actions workflows, VS Code settings), and API testing frameworks. Libraries: ajv in Node.js (fastest), jsonschema in Python, and json-schema-validator in Java.

JSON vs Alternative Data Formats

Understanding when to use alternatives to JSON is important for building efficient systems:

• YAML: More readable for configuration files — supports comments, multi-line strings, and cleaner syntax for nested structures. Used in Docker Compose, Kubernetes, and CI/CD pipelines. Too ambiguous and slow to parse for production APIs.
• TOML: Designed to be obvious and unambiguous for configuration. Used in Rust's Cargo.toml and Python's pyproject.toml. Better than YAML for structured config with nested tables.
• Protocol Buffers (protobuf): Google's binary serialisation format. 3–10× smaller than JSON, 5–10× faster to serialise/deserialise. Requires a schema and code generation step. Used in gRPC and high-performance internal APIs.
• MessagePack: Binary drop-in replacement for JSON. Same data model, binary encoding — smaller and faster. No schema required. Useful when JSON overhead is measurable but protobuf's complexity is unwanted.

For public REST APIs and web applications, JSON remains the correct default: universally supported, human-readable, and tooled everywhere. Switch to binary formats only when profiling confirms JSON is a genuine performance bottleneck.