Making Sense of JSON: Formatting, Validation, and Common Errors

You paste a curl response into your terminal and get back a single line of compressed text with hundreds of nested objects. Or a config file fails to load and the only error message is "unexpected token at position 1847." JSON is everywhere, and when it's working it's invisible — but when something's wrong, it stops everything.

This guide covers the practical side: how to read structured JSON quickly, what the most common errors mean, and how to handle the situations that actually come up in day-to-day development.

JSON in thirty seconds

JSON (JavaScript Object Notation) is a text-based format for representing structured data. It was defined by Douglas Crockford in the early 2000s as a lighter alternative to XML. It supports six data types:

• Object — a collection of key/value pairs: {"name": "Alice", "age": 30}
• Array — an ordered list: [1, 2, 3]
• String — text in double quotes: "hello"
• Number — integer or decimal: 42, 3.14
• Boolean — true or false
• Null — null

That's the entire specification. The strictness is what makes JSON reliable: it's predictable, language-independent, and trivially parseable. It's also what makes errors confusing — the parser has no tolerance for approximations.

Why minified JSON is the default

APIs serve minified (whitespace-stripped) JSON by default because it reduces payload size. A response with 50 fields and no whitespace might be 2KB; the same response formatted with newlines and indentation might be 6KB. At scale, that difference matters.

When you're debugging or reading an API response, you need it formatted. The JSON Formatter on ToolsKit takes minified JSON and produces readable output with configurable indentation and syntax highlighting in under a second.

The errors you will see repeatedly

"Unexpected token" — This is the most common JSON parse error. It means the parser encountered a character it didn't expect at that position. The reported position is where the parser gave up, which is often after the actual mistake. Common causes:

• A trailing comma after the last item in an object or array: {"a": 1,} — JSON doesn't allow this, even though JavaScript does.
• Single-quoted strings: JSON requires double quotes. {'key': 'value'} is invalid.
• Unquoted keys: {key: "value"} is JavaScript object literal syntax, not JSON.
• Comments: JSON has no comment syntax. Not //, not /* */. Any comment character will break parsing.

"Unexpected end of JSON input" — The parser reached the end of the string before the structure was complete. Usually means a missing closing brace }, bracket ], or the string was truncated in transit.

"Expected property name or '}'" — Often caused by a trailing comma before a closing brace, or by copy-pasting JSON that got corrupted mid-string.

Reading deeply nested JSON

A well-formatted JSON response from a complex API might have five or six levels of nesting. The key to reading it quickly is treating it as a tree rather than a wall of text:

• Identify the top-level type (object or array). If it's an array, find how many items it contains before diving in.
• For objects, scan the keys first before reading values. The keys give you the structure; the values are the detail.
• When you encounter an unexpected field, collapse sibling branches to reduce visual noise.

Most formatters support collapsing nested sections. The ToolsKit formatter doesn't collapse inline (it's a simple display tool), but it does show you key count and max depth so you know what you're dealing with before you start reading.

Practical tips for working with JSON day to day

Sort keys before comparing. Two API responses for the same data might have keys in different orders. Key order is not semantically meaningful in JSON, but it makes visual comparison hard. Sorting both responses by key first makes diffing them trivial.

Minify before storing. If you're storing JSON in a database column or a log entry, minify it first. It takes less space and is just as valid. Format it again when you need to read it.

Use a linter for config files. JSON config files (package.json, tsconfig.json, etc.) are easy to corrupt when editing by hand. Trailing commas, missing quotes on a key that looks like a number — these are common. Always validate before committing.

Watch for numbers that should be strings. Phone numbers, zip codes, and IDs that start with a zero should always be strings in JSON. "phone": 07911123456 will lose the leading zero when parsed; "phone": "07911123456" won't.

Be careful with large integers. JavaScript's JSON.parse uses IEEE 754 double-precision floats, which can't represent integers larger than 2^53 accurately. IDs from systems that use 64-bit integers (Twitter, for example, famously had to switch to string IDs) may be subtly corrupted when parsed in JavaScript. If you're handling large numeric IDs, treat them as strings. This is also one reason some teams switch from sequential integer IDs to UUIDs — a UUID string is always safe to parse.

The format vs minify tradeoff

Formatted JSON is for humans. Minified JSON is for machines. In production, minify. In your terminal, in logs, in config files you edit manually — format. The ToolsKit formatter supports both directions, along with key sorting, so you can go from minified API response to readable structure and back with one click.