The Complete Guide to JSON: Syntax, Types & Common Errors

JSON is the language most of the web speaks. Almost every API you call, config file you edit, and token you decode is JSON underneath. This guide covers it end to end — what JSON is, its data types, the exact syntax rules, how it compares to other formats, and the mistakes that cause most parse errors.

Prefer a focused read? Jump to What Is JSON? for the beginner's version, JSON Syntax Rules for the exact rules, JSON vs XML vs YAML vs CSV for format choice, or Common JSON Errors to fix a parse error.

What is JSON?

JSON (JavaScript Object Notation) is a lightweight, text-based format for representing structured data. It was derived from JavaScript object syntax, but it is language-independent — parsers exist for virtually every programming language, which is exactly why it became the default format for APIs and config files.

Two things make JSON so widely used: it is easy for humans to read, and trivial for machines to parse. A JSON document is just text, so it travels cleanly over HTTP, sits comfortably in a file, and drops straight into a log line.

JSON data types

JSON has a small, fixed set of value types — that constraint is a feature, not a limitation:

• String — text in double quotes: "hello". Special characters are escaped with a backslash (\n, \", \\, \uXXXX).
• Number — an integer or floating-point value: 42, -3.14, 2.5e8. There is no separate int/float type and no NaN or Infinity.
• Boolean — true or false (lowercase).
• null — an explicit empty value.
• Object — an unordered set of "key": value pairs wrapped in { }.
• Array — an ordered list of values wrapped in [ ].

Objects and arrays can nest inside each other to any depth, which is how JSON represents complex, tree-shaped data.

A worked example

{
  "name": "Ada Lovelace",
  "active": true,
  "age": 36,
  "roles": ["engineer", "author"],
  "address": {
    "city": "London",
    "postcode": null
  }
}

This single object contains a string, a boolean, a number, an array of strings, a nested object, and a null — every JSON type except a top-level array. Note that the top level can be any value: an object, an array, or even a bare "string" or 42.

The syntax rules that actually matter

Most JSON errors come from treating it like JavaScript. JSON is stricter:

1. Keys must be double-quoted strings. { name: "x" } is a JavaScript object literal, not valid JSON. It must be { "name": "x" }.
2. Strings use double quotes, never single. 'text' is invalid JSON.
3. No trailing commas. [1, 2, 3,] is valid JavaScript but invalid JSON.
4. No comments. JSON has no // or /* */. If a config format allows them (like JSONC), that is a superset, not JSON.
5. No undefined, functions, or dates. Only the six types above exist. A date is represented as a string (usually ISO 8601).
6. Whitespace between tokens is ignored, so formatting is purely for humans.

That last point is why a formatter is safe to run on any valid JSON: adding or removing indentation never changes the data, only its readability.

JSON vs XML, YAML, and CSV

A useful rule of thumb: reach for CSV for flat rows of data, YAML for config a human edits by hand, XML for document-style content, and JSON for almost everything a program produces or consumes over an API.

The errors that trip people up

When JSON.parse (or any parser) fails, it is almost always one of these:

• Single quotes where double quotes are required.
• A trailing comma after the last item in an object or array.
• Unquoted keys copied from JavaScript source.
• A missing or extra bracket/brace — the error points at where the parser gave up, which is often after the real mistake.
• Unescaped characters inside a string, such as a raw newline or a stray ".
• A leading byte-order mark (BOM) or trailing content after the JSON value.

The parser reports a position (or line and column). Counting to that offset by eye is painful, which is exactly what a formatter does for you — it points at the precise line and column so you can fix it in seconds.

Parsing JSON in code

In JavaScript, JSON support is built in: JSON.parse(text) turns a string into a value and JSON.stringify(value) turns a value back into a string. parse throws a SyntaxError on invalid input, so wrap it in a try/catch — see our dedicated guide, How to Validate JSON in JavaScript, for the reliable pattern and how to read the errors.

Every other major language ships equivalent tools: json in Python, encoding/json in Go, Jackson/Gson in Java, System.Text.Json in C#.

Best practices

• Validate at the boundary. Parse untrusted JSON in a try/catch and check the shape separately — valid syntax is not the same as the structure you expect.
• Use ISO 8601 for dates ("2026-08-09T12:00:00Z") so they sort and parse consistently.
• Keep keys consistent — pick camelCase or snake_case and stick to it.
• Don't hand-edit large JSON — format it first so structure is visible.

Try it

Paste any JSON to format, validate, and inspect it. Invalid input shows the exact line and column of the problem, and everything runs in your browser — nothing you paste is ever uploaded.