How to Format and Validate JSON: A Developer's Guide
JSON (JavaScript Object Notation) has become the universal language of data exchange on the web. Whether you're building REST APIs, storing configuration files, or passing data between microservices, you're working with JSON constantly. Yet even experienced developers run into subtle JSON errors that cause hours of debugging. This guide covers everything you need to format, validate, and troubleshoot JSON like a pro.
What Is JSON and Why Does Formatting Matter?
JSON is a lightweight text format for structured data. It's human-readable in theory, but raw JSON returned from an API or stored in a database often looks like this:
{"user":{"id":42,"name":"Alice","roles":["admin","editor"],"active":true}}
That's valid JSON, but it's painful to read when you're trying to debug a problem. Formatted (or "pretty-printed") JSON looks like this:
{
"user": {
"id": 42,
"name": "Alice",
"roles": [
"admin",
"editor"
],
"active": true
}
}
Same data, dramatically easier to scan. The indentation reveals structure at a glance. You can immediately see that roles is an array with two strings, and active is a boolean — not a string "true".
Core JSON Syntax Rules
JSON has strict rules, and even a single violation makes the entire document invalid. Here are the ones that catch developers most often:
Strings must use double quotes. Single quotes are not valid JSON.
// Invalid
{ 'name': 'Alice' }
// Valid
{ "name": "Alice" }
No trailing commas. Many developers come from JavaScript where trailing commas in objects and arrays are fine. JSON does not allow them.
// Invalid
{
"name": "Alice",
"age": 30,
}
// Valid
{
"name": "Alice",
"age": 30
}
No comments. JSON has no comment syntax. If you need self-documenting config files, consider JSONC (JSON with Comments) supported by tools like VS Code, or use a field like "_comment" as a convention.
Keys must be strings. Unlike JavaScript objects, JSON keys cannot be numbers or unquoted identifiers.
// Invalid
{ 42: "the answer" }
// Valid
{ "42": "the answer" }
Values are strictly typed. Valid JSON value types are: string, number, object, array, true, false, and null. Nothing else.
Common JSON Errors and How to Fix Them
Unexpected token errors
This usually means a syntax error — a missing comma, a stray character, or an unclosed bracket. Copy your JSON into a JSON Formatter to pinpoint the exact line number where parsing fails.
Escaped characters
Strings containing quotes, backslashes, or control characters must be escaped:
{
"path": "C:\\Users\\Alice\\Documents",
"message": "She said \"hello\"",
"newline": "line1\nline2"
}
Unicode and special characters
JSON supports Unicode. You can include characters directly or escape them:
{
"emoji": "👍",
"escaped": "A"
}
Both are valid. The escaped form A represents the letter "A".
Numbers
JSON numbers follow strict rules too. No leading zeros (except 0.5), and NaN and Infinity are not valid JSON values — even though JavaScript treats them as numbers.
// Invalid
{ "value": NaN }
{ "value": Infinity }
// Valid workaround
{ "value": null }
Validating JSON from APIs
When you're consuming an API response and something breaks, the first step is to validate the raw JSON. Common scenarios:
- API returns HTML on error. If a server returns a 500 error page as HTML, your JSON parser will fail with a confusing error. Always check the
Content-Typeheader and HTTP status code before parsing. - Encoding issues. If a response contains unescaped control characters (ASCII codes 0–31), it's invalid JSON even if it looks fine visually. A formatter will catch these.
- Truncated responses. If a connection drops mid-transfer, you get partial JSON, which fails validation. Check the response length and look for unclosed braces.
Use the JSON Formatter to paste any API response and immediately see whether it's valid and where errors occur.
Pretty-Printing vs. Minifying JSON
Pretty-printing adds whitespace and indentation for human readability. Use this when debugging, documenting APIs, or reading config files.
Minifying strips all unnecessary whitespace to reduce file size. Use this in production to save bandwidth — a large JSON payload can shrink 20-30% after minification.
Most formatters support both operations. The JSON Formatter lets you toggle between formatted and minified output instantly.
Sorting Keys
Some workflows benefit from alphabetically sorted keys — for example, when diffing two JSON objects in version control, or when comparing API responses. Sorted keys make diffs cleaner and audits easier.
Keep in mind that JSON objects are technically unordered, so sorting keys is a display/tooling concern, not a semantic one.
Working with Nested JSON
Deeply nested JSON is common in real-world APIs. Path notation helps you describe where data lives:
response.data.users[0].address.city
This reads: the data property of the response, the users array's first element, its address object's city field. When a formatter collapses and expands sections, navigating deep structures becomes much easier.
JSON Schema Validation
Beyond syntax validation, JSON Schema lets you validate the structure and types in a JSON document. A simple schema might look like:
{
"type": "object",
"required": ["id", "name"],
"properties": {
"id": { "type": "integer" },
"name": { "type": "string" },
"age": { "type": "integer", "minimum": 0 }
}
}
This validates that a JSON object has the required id (integer) and name (string) fields. Schema validation is essential in CI pipelines to catch breaking API changes before they reach production.
FAQ
Can JSON contain functions or dates?
No. JSON has no date or function type. Dates are typically represented as ISO 8601 strings ("2026-06-20T00:00:00Z") or Unix timestamps (integers). Functions cannot be serialized.
What's the difference between JSON and JSON5? JSON5 is a superset of JSON that allows single quotes, comments, trailing commas, and unquoted keys. It's useful for config files but not for API communication, since most parsers don't support it.
Is whitespace significant in JSON? Whitespace outside of strings is ignored. Whitespace inside a string value is significant.
Why does my JSON look valid but still fails to parse? Check for a BOM (byte order mark) at the start of the file, invisible Unicode characters, or Windows-style line endings causing issues in certain parsers. A good formatter will strip or highlight these.
What's the maximum JSON file size I should try to format in-browser?
Most in-browser formatters handle up to a few megabytes comfortably. For files larger than 10 MB, consider using command-line tools like jq instead.