ToolsDoc

JSON Formatting and Validation: A Beginner's Guide to Reading and Fixing JSON

ToolsDoc Team
Share:FacebookXLinkedIn

If you've worked with APIs, config files, or modern web apps for more than five minutes, you've run into JSON — and probably also run into the special frustration of a JSON parser rejecting your file with an unhelpful error like "unexpected token" and a line number that doesn't quite point at the actual problem. This guide covers what JSON actually is, the syntax rules that cause the most errors, and how to debug broken JSON efficiently.

What JSON Actually Is

JSON (JavaScript Object Notation) is a lightweight, text-based format for representing structured data — objects, arrays, strings, numbers, booleans, and null. It was derived from JavaScript's object literal syntax but is now language-agnostic; nearly every programming language has a JSON parser, which is exactly why it became the default format for APIs, config files, and data interchange.

A JSON document is built from just a few building blocks:

{
  "name": "ToolsDoc",
  "isFree": true,
  "toolCount": 350,
  "categories": ["calculators", "converters", "generators"],
  "founder": null
}

That's an object (the outer { }), containing key-value pairs, one of which holds an array ([ ]), plus a string, a boolean, a number, and a null.

The Syntax Rules That Trip People Up

JSON looks almost identical to a JavaScript object literal, which is exactly why it's so easy to write invalid JSON without realizing it — JavaScript is more forgiving than the JSON spec. The differences that cause the most errors:

  1. Keys must be double-quoted strings. {name: "value"} is valid JavaScript but invalid JSON — it must be {"name": "value"}. Single quotes around keys or values are also invalid; JSON strings must use double quotes exclusively.

  2. No trailing commas. ["a", "b", "c",] will fail JSON parsing because of that last comma before the closing bracket, even though many programming languages tolerate it just fine.

  3. No comments. JSON has no comment syntax at all — not //, not /* */. If you need to annotate a JSON file, you either strip the comments before parsing or switch to a format that supports them (like JSON5 or YAML).

  4. No unquoted values. Strings must always be in double quotes. {"active": yes} is invalid — booleans must be the literal unquoted true or false, and strings must always be quoted, with no in-between.

  5. Numbers can't have leading zeros or trailing decimal points. 007 and 5. are both invalid; 7 and 5.0 are fine.

  6. No undefined, no functions, no special JS values. JSON supports exactly six types: object, array, string, number, boolean, and null. Anything else (like JavaScript's undefined, NaN, or a function) has no valid JSON representation.

Reading a Parser Error

Most JSON parsers report an error position (a line and column, or a character offset), but the location is often where the parser gave up, not necessarily where the actual mistake is. A missing closing brace, for example, often isn't detected until the parser reaches the end of the file and realizes something never got closed — so the reported error might point to the last line even though the real problem is much earlier.

A more reliable debugging approach:

  1. Format the JSON first. Pretty-printing (adding consistent indentation and line breaks) makes structural problems — a missing bracket, a misplaced comma — dramatically easier to see visually than staring at a single unbroken line.
  2. Check brackets and braces balance. Count opening and closing {, }, [, ] — an imbalance anywhere is a guaranteed parse failure.
  3. Look at the last item before every closing bracket. Trailing commas are one of the single most common causes of "valid-looking" JSON that still fails to parse.
  4. Check for stray quotes inside strings. An unescaped " inside a string value will prematurely close that string and corrupt everything after it, often producing an error message far from the actual mistake.

Formatting vs Validating: Two Different Jobs

It's worth separating these two operations, since they solve different problems:

  • Formatting takes valid JSON and reformats its whitespace and indentation for readability. It won't tell you if the JSON is broken — a formatter that can't parse the input will simply fail, not "fix" it.
  • Validating checks whether a JSON document conforms to the spec at all, and reports exactly where it breaks if it doesn't. This is the step you want before formatting, if you're not sure the JSON is even structurally sound.

A practical workflow is: validate first to catch structural errors, then format the confirmed-valid JSON for readability once you know it actually parses.

Tools for the Job

  • JSON Formatter — pretty-print and re-indent valid JSON instantly.
  • JSON Validator — check whether a JSON document is well-formed, with error details when it isn't.
  • JSON to CSV — convert JSON arrays of objects into a spreadsheet-friendly format.

JSON's strictness is a feature, not a bug — it's exactly what makes it reliably parseable across every language without ambiguity. The syntax rules feel picky at first, but once you know the handful of ways JSON differs from a casual JavaScript object, most "unexpected token" errors become a two-second fix instead of a five-minute hunt.