JSON for Beginners: Format, Validate and Fix It

You open a config file or an API response and see a wall of curly braces and colons crammed onto one line. That's JSON, and most people's first real encounter with it is troubleshooting why it won't load. This guide covers the syntax rules that actually matter, the handful of mistakes that cause nearly every error, and how to fix a broken file without guessing.

What JSON actually is

JSON stands for JavaScript Object Notation, but despite the name it isn't tied to JavaScript anymore — it's a plain-text format for storing and exchanging data that pretty much every programming language can read and write. At its core, JSON is just a structured way to write down two things: pairs of labels and values (like "name": "Alex"), and lists of items (like ["red", "green", "blue"]).

You'll run into JSON constantly without necessarily writing it yourself: it's what most APIs send back when an app talks to a server, it's how many apps store settings and config files, and it's a common format for exporting data from spreadsheets, databases, and web forms. Learning to read it — even just enough to spot what's broken — is a genuinely useful, low-effort skill.

The building blocks: objects, arrays, and values

JSON has exactly two container types. An object is a set of key-value pairs wrapped in curly braces: { "name": "Alex", "age": 29 }. An array is an ordered list of values wrapped in square brackets: [ "red", "green", "blue" ]. Objects and arrays can hold other objects and arrays inside them, which is how JSON represents anything from a single setting to a deeply nested API response.

The values themselves can only be one of six types: a string (in double quotes), a number, a boolean (true or false), null, an object, or an array. That's the entire list — there's no date type, no function, nothing custom. Anything more complex gets represented using these six building blocks.

The syntax rules that actually matter

Almost every JSON error traces back to one of a small handful of rules. Memorize these and you can debug most broken files on sight:

• Keys must be in double quotes. {name: "Alex"} is invalid; it must be {"name": "Alex"}.
• Strings must use double quotes, never single quotes. 'Alex' is invalid JSON, even though it's valid in JavaScript.
• No trailing commas. A comma after the last item in an object or array breaks the whole file.
• Every opening brace or bracket needs a matching close. { pairs with }, [ pairs with ].
• No comments allowed. JSON has no // or /* */ syntax, unlike JavaScript or most config formats.

Every one of these rules exists to make JSON simple and unambiguous for machines to parse — the tradeoff is that a single misplaced comma or quote mark makes the whole file unreadable, with no partial credit.

Worked example: a broken file, fixed

Here's a JSON snippet with three separate errors, the kind you'll actually run into:

Broken:

{
  name: 'Alex',
  "age": 29,
  "skills": ["writing", "design",]
}

Three problems: the key name isn't in quotes, its value uses single quotes instead of double, and there's a trailing comma after "design" in the array. Here's the corrected version:

Fixed:

{
  "name": "Alex",
  "age": 29,
  "skills": ["writing", "design"]
}

This is exactly the kind of fix a JSON formatter handles automatically — it'll point at the exact line and character where parsing failed, which is far faster than scanning by eye.

Common syntax errors and how to spot them

Beyond the three in the example above, a few other errors show up often. Missing commas between items — forgetting the comma between two key-value pairs in an object is easy to miss when everything's on one line. Unescaped quotes inside a string — if a value itself contains a double quote, like a name with an embedded quotation mark, it has to be escaped or it'll prematurely end the string. Mismatched brackets — closing an array with } instead of ], or vice versa, especially in deeply nested structures. Using NaN, undefined, or unquoted Infinity — these are valid in JavaScript but not in JSON; only null is allowed for a missing value.

Most parsers will tell you the line and column where they gave up, which is usually right at or just after the actual mistake — start looking there rather than re-reading the whole file top to bottom.

Formatting (pretty-printing) vs. minifying

Formatting, also called pretty-printing, takes compact JSON and adds line breaks and indentation so nested structure is easy to read at a glance. This is what you want while writing, debugging, or reviewing a file by hand.

Minifying does the opposite — it strips all unnecessary whitespace to shrink the file to the smallest possible size. Whitespace between JSON tokens has no meaning to a machine, so removing it changes nothing functionally, but it does make the file unreadable to humans. Minified JSON is what you typically want for production, since smaller files transfer faster over a network — but you'd switch back to a formatted view any time you need to actually read or edit it. A JSON formatter handles both directions instantly, so you're never stuck manually adding or stripping indentation.

Validating JSON

Validating means checking whether a file follows JSON's rules correctly, independent of formatting. A file can be perfectly readable to a human and still be invalid — for example, missing a single closing brace at the very end, which is easy to miss visually but will fail every single parser.

The reliable way to validate is to run the file through an actual parser rather than eyeballing it, since parsers catch every rule violation without exception, including the subtle ones like a stray trailing comma buried three levels deep in a nested array. Most formatting tools validate as a side effect of formatting: if the file can't be parsed, it can't be formatted either, and you'll get an error pointing at the problem instead of a tidied-up result.

Nested objects and arrays explained

Real-world JSON is rarely flat — it's usually objects containing arrays containing more objects, several levels deep. For example, a single "user" object might contain an array of "orders," and each order might contain its own array of "items," each of which is its own object with a name and price.

The trick to reading nested JSON without getting lost is to track indentation level by level rather than trying to hold the whole structure in your head at once: find the outermost {, identify its direct keys, and only then drill into whichever nested value you actually need. Formatted (pretty-printed) JSON makes this dramatically easier than minified JSON, since indentation visually maps to nesting depth — another reason to format a file before trying to read through it.

Escaping special characters

Because double quotes and backslashes have special meaning in JSON strings, they need to be "escaped" with a backslash when they appear inside a value. A literal double quote inside a string is written as \", and a literal backslash is written as \\. Newlines inside a string are written as \n rather than an actual line break, since a raw line break inside an unescaped string is invalid.

This mostly matters when you're hand-editing JSON that contains user-generated text, file paths (which are full of backslashes on Windows), or any text pulled from elsewhere that might already contain quote marks. When JSON is generated programmatically by a library or API, escaping is handled automatically — it's really only a manual pitfall when you're typing or pasting content directly into a file yourself.

Where JSON actually gets used

APIs: when an app requests data from a server — weather, stock prices, a list of products — the response almost always comes back as JSON, since it's compact and every major language can parse it natively. Config files: many apps and dev tools (package managers, editors, build tools) store their settings in a JSON file you might occasionally need to hand-edit. Data exchange and export: exporting data from a database, spreadsheet, or web form often defaults to JSON because it preserves structure (unlike a flat CSV) while staying human-readable and universally supported.

JSON vs. XML vs. YAML

JSON isn't the only format for structured data — XML and YAML solve the same problem with different tradeoffs. Here's how they compare on the things that matter most day to day:

In short: JSON wins on universal support and being the default for web APIs, YAML wins on being the easiest for humans to hand-write, and XML persists mostly in older enterprise systems where it was already deeply embedded before JSON became popular.

Common mistakes people make

The single most common mistake is using single quotes instead of double quotes, usually because it's a habit carried over from JavaScript or Python, where single quotes work fine. Close behind is leaving a trailing comma after the last item in a list — a totally harmless habit in JavaScript that will break JSON every time.

Another frequent mistake is manually editing minified JSON without formatting it first — trying to spot a missing bracket in a single unbroken line of text is far harder than it needs to be. And a subtler one: assuming a number stored as a string (like "29" instead of 29) will behave the same as a real number downstream — some systems will parse it correctly, but others won't perform math or comparisons on it until it's explicitly converted.

Best practices for working with JSON

Keep keys consistent — pick one naming style (like camelCase or snake_case) and stick with it throughout a file rather than mixing conventions. Format before you read or edit anything by hand; trying to parse minified JSON visually wastes time a formatter can save instantly. Validate before you trust a file, especially if it came from outside your own tools — a hand-edited or copy-pasted file is far more likely to have a stray typo than one generated programmatically. And keep values reasonably typed: use real numbers and booleans rather than storing everything as strings, since it saves downstream code from having to convert types before it can use the data.

Limitations worth knowing

JSON is deliberately minimal, and that has real tradeoffs. There's no native date type, so dates are almost always stored as strings and have to be parsed by whatever's reading the file — formats vary, so this is a common source of bugs. There's no way to add comments, which makes it awkward for config files where you'd like to explain why a setting is set a certain way (this is one reason YAML has become more popular for that specific use case). And very large numbers can lose precision in some parsers, since JSON's number type doesn't guarantee the same precision every language's native number type does. None of these are dealbreakers for JSON's core job — data exchange — but they're worth knowing before you reach for it as a general-purpose file format for everything.

Using a formatter instead of doing it by hand

For anything beyond a tiny snippet, a dedicated JSON formatter is faster and more reliable than manually fixing indentation, quotes, and commas. Paste in a file, and it formats, validates, and flags the exact line of any syntax error in one step — no need to install anything or write a script just to check whether a file is valid.

Free tools mentioned here

Frequently asked questions