How to Format JSON: A Complete Guide for Developers

JSON (JavaScript Object Notation) is the most common data interchange format on the web. APIs return it, configuration files use it, and databases store it. Yet working with raw JSON can be painful when it arrives as a single unformatted line. Knowing how to format, validate, and manipulate JSON is an essential developer skill.

JSON Syntax Rules

JSON is built on two structures: objects (key-value pairs wrapped in curly braces) and arrays (ordered lists wrapped in square brackets). Understanding the syntax rules prevents most parsing errors:

• Keys must be strings enclosed in double quotes. Single quotes are not valid.
• Values can be strings, numbers, booleans (true/false), null, objects, or arrays.
• Trailing commas after the last item are not allowed.
• Comments are not part of the JSON specification.
• Numbers cannot have leading zeros (except 0 itself or decimals like 0.5).

Common JSON Errors

When JSON.parse() throws an error, the cause is almost always one of these issues:

• Trailing commas. The line {"a": 1, "b": 2,} will fail because of the comma after 2.
• Single quotes. Using {'key': 'value'} instead of double quotes.
• Unquoted keys. Writing {key: "value"} without quoting the key.
• Missing commas. Forgetting a comma between properties or array elements.
• Special characters. Unescaped newlines or tabs inside string values.

Formatting vs. Minifying

Formatting (also called beautifying or pretty-printing) adds indentation and line breaks to make JSON human-readable. Minifying does the opposite, removing all unnecessary whitespace to reduce file size. Both operations preserve the data exactly. The content does not change, only the presentation.

In JavaScript, JSON.stringify(obj, null, 2) produces formatted output with 2-space indentation. JSON.stringify(obj) without the third argument produces minified output. The second argument is a replacer function or array that lets you filter which properties are included.

When to Validate JSON

You should validate JSON whenever it comes from an untrusted or external source. This includes API responses from third-party services, user-submitted data, configuration files edited by hand, and data imported from other systems. Validation catches syntax errors early and prevents confusing runtime failures deeper in your application.

For structural validation (checking that the data has the right shape, not just valid syntax), consider using JSON Schema. Libraries like Ajv or Zod can validate that an API response matches your expected structure before you try to use it.

JSON in APIs

REST APIs overwhelmingly use JSON as their data format. When sending JSON in HTTP requests, set the Content-Type header to application/json. When receiving JSON, parse the response body using the built-in response.json() method in the Fetch API. Always wrap parsing in a try-catch block to handle malformed responses gracefully.

Best Practices

• Use consistent indentation (2 or 4 spaces) in configuration files and committed JSON.
• Minify JSON in production API responses to reduce bandwidth.
• Use a formatter tool to inspect unfamiliar JSON structures before writing parsing code.
• Be careful with large numbers. JSON numbers are IEEE 754 floats, so integers larger than 2^53 lose precision. Some APIs send large IDs as strings for this reason.
• Consider JSON5 or JSONC for configuration files where you need comments, but remember these are not standard JSON.