JSON for Beginners: What It Is, How It Works, and Common Mistakes

JSON (JavaScript Object Notation) is the most widely used data format on the internet. If you've ever built a web app, called an API, or opened a config file, you've encountered JSON. This guide explains what it is, how it works, and the common mistakes that make JSON invalid.

---

What JSON actually is

JSON is a text-based data format. It stores structured data — objects, lists, numbers, strings, booleans — in a way that humans can read and machines can parse reliably.

It was invented in the early 2000s by Douglas Crockford as a simpler alternative to XML for transmitting data between web servers and browsers. Today it's the default format for:

• REST API responses (what you get when you fetch data from Twitter, GitHub, Google Maps, etc.)
• Configuration files (package.json, .eslintrc.json, settings.json)
• Data storage in NoSQL databases (MongoDB, Firestore, DynamoDB)
• Request bodies sent to servers from web applications

The reason JSON won over XML is simplicity. Both can represent the same data, but JSON is more compact, easier to read, and maps directly to native data structures in most programming languages.

---

JSON syntax rules

A JSON document must follow exactly these rules:

1. Values are one of six types:

• String — text in double quotes: "hello", "New York", ""
• Number — integer or decimal: 42, 3.14, -7, 1.5e10
• Boolean — true or false (no quotes, lowercase)
• Null — null (no quotes, lowercase)
• Object — key-value pairs in curly braces: {"name": "Alice", "age": 30}
• Array — ordered list in square brackets: [1, 2, 3] or ["a", "b", "c"]

2. Object keys must be strings in double quotes

{"name": "Alice"}   // valid
{name: "Alice"}     // INVALID — key must be quoted
{'name': 'Alice'}   // INVALID — must use double quotes, not single

3. No trailing commas

{"a": 1, "b": 2}    // valid
{"a": 1, "b": 2,}   // INVALID — trailing comma after last item
[1, 2, 3]           // valid
[1, 2, 3,]          // INVALID — trailing comma

4. No comments

// This is a comment — NOT VALID IN JSON
{"key": "value"}

JSON has no comment syntax. This surprises many developers coming from JavaScript or YAML. Some tools (like VS Code for .json files) support JSONC (JSON with Comments) as an extension, but standard JSON parsers reject comments.

5. Strings use only double quotes

Single quotes for strings ('hello') are a JavaScript convention — they are not valid in JSON.

6. No undefined, functions, or special types

JavaScript's undefined, NaN, Infinity, functions, and Symbol cannot be represented in JSON.

---

A real-world example

This is what a typical API response looks like:

{
  "user": {
    "id": 1847,
    "name": "Maria Santos",
    "email": "maria@example.com",
    "isPro": true,
    "joinedAt": "2025-03-15",
    "tags": ["developer", "designer"],
    "address": {
      "city": "Lisbon",
      "country": "PT"
    }
  },
  "metadata": {
    "requestId": "a1b2c3",
    "duration": 0.043
  }
}

This response contains:

• A string ("Maria Santos")
• A number (1847, 0.043)
• A boolean (true)
• An array of strings (["developer", "designer"])
• Nested objects ("address" inside "user", plus "metadata" at the top level)
• A date stored as a string (JSON has no date type — dates are represented as ISO 8601 strings by convention)

---

Common JSON errors and how to fix them

Single quotes instead of double quotes

Invalid:

{'name': 'Alice'}

Valid:

{"name": "Alice"}

This is the single most common JSON error. JavaScript allows single quotes in code, but JSON is not JavaScript — it requires double quotes for both keys and string values.

Trailing comma

Invalid:

{
  "a": 1,
  "b": 2,
}

Valid:

{
  "a": 1,
  "b": 2
}

This trips up developers used to JavaScript (which allows trailing commas in modern JS). Paste your JSON into our JSON Formatter and it will pinpoint the exact line where the trailing comma is.

Unquoted key

Invalid:

{name: "Alice"}

Valid:

{"name": "Alice"}

Missing comma between items

Invalid:

{
  "a": 1
  "b": 2
}

Valid:

{
  "a": 1,
  "b": 2
}

Comment in JSON

Invalid:

{
  // This is the user's name
  "name": "Alice"
}

Valid: Remove the comment entirely. If you need documentation, add it as a separate JSON key like "_comment": "This is the user's name" — though this is a hack, not a standard.

---

How to debug invalid JSON

If you have a JSON string that's failing to parse, the fastest approach:

1. Paste into a JSON validator. The JSON Formatter and Validator uses the browser's native JSON.parse() to validate and reports the exact line and column of the first error.

2. Read the error message literally. "Unexpected token ',' at line 12, column 5" means there's a comma where the parser didn't expect one — likely a trailing comma. "Unexpected token 'n' at line 3" often means null is misspelled or a string is missing its quotes.

3. Check for encoding issues. Some APIs return JSON with a BOM (Byte Order Mark) at the start, or curly quotes (" instead of ") from word processing software. These cause immediate parse failures.

4. Validate incrementally. For large JSON blobs, comment out sections (or delete temporarily) to isolate which section is causing the error.

---

JSON in config files

The most common non-API use of JSON is configuration files. package.json defines an npm package. tsconfig.json configures TypeScript. .eslintrc.json configures ESLint.

One frustration: JSON's lack of comment support makes config files harder to document. This is why some tools (VS Code's settings, for example) use JSONC — JSON with Comments — as a superset. Standard JSON parsers still reject JSONC, so be careful which file type you're editing.

---

FAQ

Is JSON the same as JavaScript? No. JSON is inspired by JavaScript object notation but is a separate, language-independent format. Valid JSON is a subset of valid JavaScript, but not the other way around — JavaScript code is not valid JSON. Any programming language can parse JSON: Python, Ruby, Go, Java, and hundreds of others.

Can JSON represent dates and times? Not natively — JSON has no date type. By convention, dates are stored as ISO 8601 strings ("2026-06-07T09:00:00Z"). When you receive a date from an API as a JSON string, your code is responsible for parsing it into a date object.

What's the difference between JSON and YAML? Both are data formats for configuration and data exchange. YAML is more human-readable (less punctuation, indentation-based structure) and supports comments, but is more complex to parse and has a larger specification. JSON is stricter, more predictable, and faster to parse. JSON is the default for APIs; YAML is common for configuration files (Docker, Kubernetes, GitHub Actions).

Why can't JSON have comments? By design. Crockford intentionally excluded comments to prevent people from using comments as config parsing directives (like configuration files do with #include or # set-option: prefixes), which would complicate parsers and create nonstandard dialects. The decision is controversial but the spec is clear.

What is "pretty-printed" vs "minified" JSON? Pretty-printed JSON has consistent indentation and line breaks — easier for humans to read. Minified JSON has all whitespace removed — smaller file size, harder to read. APIs often return minified JSON to save bandwidth. Use our JSON Formatter to pretty-print or minify any JSON.