JSON Syntax Errors Explained, and How to Fix Them

An API returns one long line of text. A configuration file refuses to load and the error says “Unexpected token”. Both are JSON problems, and both are easier once the JSON is laid out properly and checked against the rules.

What is JSON?

JSON (JavaScript Object Notation) is a text format for structured data, defined in RFC 8259. Almost every web API uses it, and so do many configuration files. It has only six kinds of value:

Objects and arrays can contain each other to any depth. Here is a small valid document:

{
  "name": "Ada Lovelace",
  "born": 1815,
  "languages": ["English", "French"],
  "mathematician": true,
  "spouse": null
}

Formatting and minifying

Formatting, also called pretty-printing or beautifying, puts each value on its own line and indents nested levels, as above. Minifying does the opposite and removes every space and line break that isn’t inside a string:

{"name":"Ada Lovelace","born":1815,"languages":["English","French"],"mathematician":true,"spouse":null}

Both contain exactly the same data. Format JSON when people need to read it: debugging, code review, documentation. Minify it when size matters: request bodies, storage, or a value that has to fit on one line.

Indentation is a style choice. Two spaces is the most common in web projects, four is common in Python, and tabs are used where a team prefers them. Pick one and use it consistently.

Using the formatter

Paste the JSON into the JSON formatter and validator, then choose Format, Minify or Validate; when there’s an error, “Show the error in my JSON” jumps to it. The formatter only changes whitespace. Numbers such as 2.50 and very large integers stay exactly as you wrote them, which isn’t true of tools that parse the JSON and write it out again.

What are the most common JSON errors?

These are the errors behind most invalid JSON, with the message the validator shows for each.

A trailing comma

{"name": "Ada", "tags": ["math", "code",]}

“Remove the comma before ]: JSON doesn’t allow trailing commas.” JavaScript accepts a comma after the last item; JSON doesn’t. Delete it.

Single quotes

{'name': 'Ada'}

“Strings and keys must use double quotes ("), not single quotes (').” Replace every single quote around a string or key.

Keys without quotes

{name: "Ada"}

“Keys must be in double quotes.” This is valid in a JavaScript object, but not in JSON. Write "name".

A missing comma

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

“A comma is missing between two properties.” This often happens when lines are copied from different places.

Numbers with leading zeros

{"id": 007}

JSON numbers can’t start with 0 unless the number is 0 or a decimal like 0.5. Write 7, or use a string: "007".

Comments

JSON has no comments. Some tools accept them in variants such as JSONC or JSON5, but APIs expect standard JSON. Remove // and /* */ comments, or move the note into a field.

Formatting JSON in code

• JavaScript: JSON.stringify(data, null, 2) formats with 2 spaces; JSON.stringify(data) minifies.
• Python: json.dumps(data, indent=2), or python -m json.tool file.json from the command line.
• Command line: jq . file.json formats, and jq -c . file.json minifies.

These parse the data first, so they will rewrite 2.50 as 2.5 and may round integers beyond 9,007,199,254,740,991 in JavaScript.

JSON next to other encodings

JSON often travels inside other formats. A value in a URL query string must be percent-encoded, so {"id":42} becomes %7B%22id%22%3A42%7D in the URL encoder; see how URL encoding works. Tokens and data fields sometimes carry JSON as Base64 instead: {"id":42} is eyJpZCI6NDJ9, which the Base64 decoder turns back into JSON you can format.