JSON Formatting Best Practices for Developers

Valid JSON follows a short list of strict rules: keys and strings in double quotes, no trailing commas, no comments, and only six kinds of value (string, number, object, array, true/false and null). Almost every "Unexpected token" error comes from breaking one of those rules. Once the syntax is valid, good formatting is about consistency: a fixed indent, a predictable key order and one style across the project.

To check and pretty-print a document right now, paste it into the JSON Formatter. It parses the input, reports the parser's error message if the JSON is invalid, and re-prints it with 1, 2 or 4 spaces of indentation, or minified onto a single line.

The JSON Syntax Rules

JSON is defined by RFC 8259 and ECMA-404. The whole grammar fits on one page, and these are the rules that matter day to day.

What JSON does not have is just as important: no comments, no trailing commas, no undefined, no dates (dates are usually written as ISO 8601 strings such as "2026-10-10T14:30:00Z"), and no functions.

Escaping inside strings

A literal line break or tab inside a string is invalid. Control characters must be escaped: \n for a new line, \t for a tab, \" for a double quote and \\ for a backslash. Any character can also be written as a Unicode escape such as \u00e9 for é. Windows paths are a frequent trap: C:\Users must be written as "C:\\Users" in JSON.

Common JSON Syntax Errors and What They Mean

Parser messages vary between browsers and languages, but they always point at the first character the parser could not accept. The messages below are what Chrome and Node.js report, which is also what you will see in the JSON Formatter if you use Chrome.

Trailing comma

{"name": "Ada", "age": 36,}

Chrome reports "Expected double-quoted property name in JSON at position 26". The parser saw a comma and expected another key. Delete the comma after the last item. This is the single most common error, because JavaScript, Python and most modern languages allow trailing commas and JSON does not.

Single quotes or unquoted keys

{'name': 'Ada'} and {name: "Ada"}

Both produce "Expected property name or '}'". Replace single quotes with double quotes and quote every key. This often happens when a JavaScript object literal or a Python dictionary printed with print() is pasted in as if it were JSON.

Missing comma between items

{"name": "Ada" "age": 36}

Reported as "Expected ',' or '}' after property value". Look at the end of the line before the position the error mentions.

Comments

A line starting with // or a /* block */ produces "Unexpected token '/'". Strip comments before parsing. If you need comments in configuration files, use a format that supports them, such as JSONC (used by VS Code settings and tsconfig.json), JSON5 or YAML, and be aware that a strict JSON parser will still reject those files.

Invalid values

NaN, Infinity, undefined and numbers with leading zeros such as 012 all fail. Use null for a missing value and store special numbers as strings if you must keep them.

Raw line breaks in strings

A string that spans two lines gives "Bad control character in string literal". Replace the line break with \n.

Unbalanced brackets

A missing closing brace or bracket usually produces "Unexpected end of JSON input". Pretty-printing the part that does parse makes the mismatch easy to see, because the indentation stops lining up where the structure breaks.

Formatting Conventions That Make JSON Easier to Work With

Once a file is valid, formatting decides how pleasant it is to read, review and diff.

Pick one indent and enforce it

Two spaces is the most common choice in web projects and what npm uses for package.json; four spaces is common in Python projects. Either is fine. What causes pain is mixing them, because every reformat shows up as a noisy diff. Let a tool such as Prettier or your editor's formatter apply the indent on save.

Keep key order stable

JSON objects are unordered by definition, but people read top to bottom. Put identifying fields (id, name, type) first and group related keys together. For generated files that are committed to version control, sorting keys alphabetically keeps diffs small, because the same data always serialises the same way.

Use consistent key naming

Choose camelCase or snake_case for the whole API and stick to it. Mixing userId and user_id in one payload forces every consumer to handle both.

Avoid duplicate keys

RFC 8259 says names within an object should be unique, and parsers handle duplicates differently. JavaScript's JSON.parse keeps the last value silently, so {"d": 1, "d": 2} becomes {"d": 2}. A formatter that re-serialises the data will therefore drop the earlier duplicate.

Watch out for very large numbers

JavaScript stores every number as a 64-bit float, which represents integers exactly only up to 9,007,199,254,740,991. A larger ID such as 12345678901234567890 comes back from JSON.parse as 12345678901234567000. Any browser-based formatter that parses and re-prints JSON, including ours, has the same limitation, so APIs that use 64-bit IDs (Twitter/X famously did) often send them as strings as well.

Minify for transport, pretty-print for people

Whitespace is ignored by parsers, so production APIs usually send minified JSON to save bytes, while configuration files and fixtures are stored pretty-printed so humans can review them. Compression such as gzip removes much of the size difference over the wire, but minifying still helps for large payloads. The JSON Minifier strips the whitespace, and the JSON Size Calculator shows how many bytes you save.

Validate Before You Ship

Formatting and validating are related but different. A formatter needs valid input, so it fails on syntax errors; a validator focuses on telling you exactly what is wrong and where. When a payload is rejected, paste it into the JSON Validator to find the problem, fix it, then run it through the formatter for a clean copy. For structural checks beyond syntax, such as required fields and value types, look at JSON Schema, which most languages support through a library.

How to Use the JSON Formatter

Everything runs locally in your browser, so you can paste API responses or configuration files without the data leaving your machine. Note that, like JSON.parse itself, the formatter normalises some values when it re-prints them: 1.0 becomes 1, 1e3 becomes 1000 and Unicode escapes are shown as the characters they represent. Open the JSON Formatter to clean up your next file, and see JSON to CSV if you need the data in a spreadsheet.