JSON basics: syntax, common errors and how to fix them

JSON (JavaScript Object Notation) is the most common format for exchanging data between web services, apps and configuration files. Almost every API returns JSON, and tools from VS Code to package managers store settings in it. It is easy to read, but parsers are strict: one misplaced comma breaks the whole document. This guide covers the syntax, the errors you’ll hit most, and when CSV is a better choice. Paste any JSON into our JSON formatter to validate and pretty-print it.

The syntax in one example

{
  "id": 1042,
  "name": "Ada Lovelace",
  "email": "[email protected]",
  "active": true,
  "balance": 1250.75,
  "manager": null,
  "roles": ["admin", "editor"],
  "address": {
    "city": "London",
    "postcode": "SW1A 1AA"
  }
}

JSON is built from two structures:

• Objects: unordered sets of "key": value pairs inside curly braces { }, separated by commas.
• Arrays: ordered lists of values inside square brackets [ ], separated by commas.

Data types

There is no date type. Dates are usually written as ISO 8601 strings ("2026-10-08T14:30:00Z") or as Unix timestamps (1791460800); see our Unix timestamp guide.

The current standard is RFC 8259 (also ECMA-404). JSON text exchanged between systems must be encoded as UTF-8.

Escaping inside strings

Some characters must be escaped with a backslash:

A Windows path is therefore written "C:\\Users\\ada", and a quote inside text as "She said \"hi\"". Raw line breaks inside a string are not allowed.

The most common JSON errors

1. Trailing comma

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

JavaScript objects allow a comma after the last item; JSON does not. Remove it.

2. Single quotes

{ 'name': 'Ada' }

Only double quotes are valid, for both keys and string values.

3. Unquoted keys

{ name: "Ada" }

Every key must be a quoted string.

4. Comments

{
  // user id
  "id": 1
}

Comments are not allowed. Some config files use JSONC (JSON with comments, e.g. VS Code settings) or JSON5, but strict parsers reject them. Move notes into a field such as "_comment" if you must.

5. Missing comma or bracket

Unexpected token or Expected ',' or '}' errors usually point to the line after the real problem. Check the end of the previous line. A formatter that shows the line and column helps enormously.

6. Wrong literal case or non-JSON values

True, NULL, undefined, NaN and functions are invalid. Use true, null, or omit the field.

7. Byte order mark or invisible characters

Files saved with a BOM, or text copied from documents with “smart quotes” (“ ”), can fail to parse. Retype the quotes or save as UTF-8 without BOM.

Formatting and validating

• Pretty-printing adds indentation and line breaks so humans can read nested data.
• Minifying removes whitespace to reduce size for transport.
• Validating checks the syntax; schema validation (with JSON Schema) checks that required fields exist and have the right types.

In code:

// JavaScript
const data = JSON.parse(text);          // throws SyntaxError on invalid JSON
const pretty = JSON.stringify(data, null, 2);

# Python
import json
data = json.loads(text)
pretty = json.dumps(data, indent=2, ensure_ascii=False)

On the command line, jq . file.json validates and pretty-prints.

JSON vs CSV

Choose CSV for tabular data that people will open in Excel or Google Sheets. Choose JSON when records have nested or variable fields, or when the data goes to or from an API. Our CSV to JSON converter converts between the two; nested JSON is flattened into columns such as address.city when converted to CSV.

CSV pitfalls when converting

• Commas inside values must be quoted: "London, UK".
• Leading zeros (postcodes, phone numbers) may be stripped by spreadsheet apps.
• Different regions use ; as the separator because , is the decimal mark.

Good practices

• Use consistent key naming (camelCase or snake_case) throughout.
• Prefer ISO 8601 strings for dates, with a time zone.
• Represent money as integers in the smallest unit (pence, cents) or as strings, to avoid floating-point rounding.
• Very large integers (over 2^53 − 1) lose precision in JavaScript; send them as strings.
• Never use eval() to parse JSON.

Checklist

• Double quotes for every key and string.
• No trailing commas, no comments.
• true, false, null in lowercase.
• Escape quotes, backslashes and line breaks in strings.
• Validate with a formatter before shipping config or API payloads.
• Use CSV for flat tables, JSON for nested data.

Working with patterns inside JSON strings? See our regex cheat sheet.