JSON Formatting Guide: How to Format, Validate, and Debug JSON

JSON (JavaScript Object Notation) is the standard data format for web APIs, configuration files, and data exchange between systems. It uses key-value pairs, nested objects, and arrays to represent structured data in a format that is both human-readable and machine-parseable. JSON is language-agnostic, which means every major programming language has built-in libraries to read and write it.

Raw JSON from an API response or a log file is almost always compact: a single line with no whitespace. This is efficient for network transmission and storage, but it is nearly impossible to read and debug when something goes wrong. A JSON formatter takes that compact string and adds indentation and line breaks to expose the structure so you can navigate it visually.

Formatting also catches syntax errors. The most common JSON bugs, such as a trailing comma, a missing quote, or a mismatched bracket, are invisible in a wall of compact text but immediately obvious in a formatted, indented view. Running every unfamiliar JSON payload through a formatter before working with it saves significant debugging time.

JSON has a strict syntax defined by RFC 8259. The rules that most developers violate are: keys must always be wrapped in double quotes (not single quotes), strings must use double quotes (not backticks or single quotes), and the last item in an object or array must not be followed by a comma (no trailing commas allowed).

Boolean values must be lowercase: true and false, not True or False or TRUE. Null must be lowercase: null, not NULL, None, or undefined. Numbers do not need quotes unless you want them treated as strings. JSON does not support comments. You cannot add single-line or block-style comments to a JSON file, and standard JSON parsers will reject them as invalid syntax.

These rules exist because JSON was designed for machine parsing above all else. Every valid JSON document can be parsed by every compliant parser in every language without ambiguity. The strictness is what makes it a reliable interchange format.

Trailing comma is the most common JSON error, particularly for developers coming from JavaScript where trailing commas are allowed in objects and arrays. The fix is to remove the comma after the last item in the object or array. Most JSON formatters highlight the exact line and position of the trailing comma.

Single quotes instead of double quotes is another frequent mistake. JavaScript developers often write JSON-like structures with single quotes because that is valid JavaScript object syntax. But JSON requires double quotes for both keys and string values. Use a JSON formatter to fix this correctly rather than a raw find-and-replace, which can break strings that contain apostrophes.

Unquoted keys are valid in JavaScript but invalid in JSON. The object literal {name: "value"} works in JavaScript but fails JSON.parse(). Wrap every key in double quotes. Similarly, undefined is not a valid JSON value (null is). If you are serializing JavaScript objects to JSON, use JSON.stringify() which handles these conversions automatically.

Beautifying (also called formatting or pretty-printing) adds indentation and line breaks so each key-value pair is on its own line with consistent indentation showing the nesting depth. The standard indentation is two spaces or four spaces. Two spaces is more compact and works better for deeply nested structures. Four spaces is more readable at shallow nesting levels.

Minifying does the opposite: it strips all whitespace to produce the most compact valid JSON possible. All keys and values remain but every unnecessary space, newline, and tab is removed. Minified JSON is smaller in bytes, which matters for API payloads transferred over a network and for config files embedded in compiled code.

The rule of thumb: use beautified JSON when a human needs to read or edit it (in documentation, in tickets, in log review). Use minified JSON when a machine needs to parse it at scale (in API responses, in database storage, in bundled app config). Both are functionally identical because a JSON parser accepts either format.

In JavaScript and Node.js, the simplest validation is a try-catch around JSON.parse(). If the input is valid JSON, parse() returns the object. If it is invalid, it throws a SyntaxError with a message that includes the position of the error. For production code, always validate untrusted JSON from user input or external APIs before using the parsed result.

In Python, use json.loads() inside a try-except block that catches json.JSONDecodeError. The error includes the line and column of the syntax problem. In Go, use json.Unmarshal() and check the error return value. For quick ad-hoc validation in the terminal, the jq command-line tool is the fastest option: pipe or pass the file to jq and if valid JSON it pretty-prints it, otherwise it shows the parse error with line and column.

For quick one-off validation in the browser, an online JSON formatter handles it in one click. Paste the JSON, click Validate, and the tool either shows the formatted output (valid) or the syntax error with the position (invalid).

Standard JSON (RFC 8259) is the format accepted by JSON.parse() and all standard library parsers. It is strict by design: no comments, no trailing commas, no single quotes. This strictness makes it universally parseable across all languages and platforms.

JSON5 is a superset of JSON that adds JavaScript-style conveniences: single quotes, trailing commas, comments, unquoted keys, and multiline strings. JSON5 is useful for config files that humans edit frequently, but it requires a dedicated parser and will fail in any context that expects standard JSON.

JSONC (JSON with Comments) is used by VS Code for its settings.json file. It looks like JSON with double-slash comments, but it is not valid standard JSON. VS Code strips the comments before parsing. Use standard JSON when writing data for APIs or inter-service communication. JSON5 or JSONC are only appropriate for human-maintained config files where the parser is under your control.

For quick one-off formatting in the browser, an online JSON formatter is the fastest option. Paste the JSON, click Format, and copy the result. The ShortIQ JSON formatter formats, minifies, and validates JSON in one click and runs entirely in your browser, so nothing is uploaded to a server.

For terminal work, jq is the standard. It formats, queries, and transforms JSON from the command line. The command jq . data.json pretty-prints the file with two-space indentation. jq is fast enough to process multi-gigabyte JSON files and is worth installing as a permanent dev tool (available on macOS via Homebrew and Linux via apt).

For IDE integration, every major editor has a JSON format-on-save option. In VS Code, set editor.formatOnSave to true and VS Code will automatically format JSON files each time you save. Combine this with an .editorconfig that specifies indent_size = 2 to keep all JSON files in the project consistently formatted without any per-developer configuration.