guide-how-to-format-and-validate-json

JSON is everywhere: API responses, configuration files, logs, browser storage. It is easy to read and easy to break. One misplaced comma makes an entire document unreadable to a parser. This guide explains the rules, shows how to format and validate JSON, and lists the errors you are most likely to meet.

The rules in one place

JSON is defined by RFC 8259 and ECMA-404. Its grammar is small:

  • A document is a single value: an object, array, string, number, true, false or null.
  • Objects are wrapped in { } and contain "key": value pairs separated by commas. Keys must be strings in double quotes.
  • Arrays are wrapped in [ ] and contain values separated by commas.
  • Strings use double quotes. Inside them, a backslash starts an escape such as \", \\, \n or \u00e9. Raw line breaks inside a string are not allowed.
  • Numbers are decimal. Leading zeros (007), a leading plus sign, hexadecimal, NaN and Infinity are not allowed.
  • There are no comments and no trailing commas.
  • Whitespace between tokens is ignored, which is why formatting and minifying can change layout without changing data.

When JSON is exchanged between systems, RFC 8259 requires UTF-8 encoding.

Formatting, minifying and validating are different jobs

Formatting (pretty-printing) adds line breaks and indentation so people can see structure. Minifying removes all optional whitespace to make the document as small as possible. Validating checks that the text follows the grammar at all.

The reliable way to do all three is to parse the text into data and serialise it again. If parsing succeeds, the JSON is valid. Serialising with an indent produces formatted output; serialising without one produces minified output. That is exactly what the Daily Dev Tools JSON formatter does, using the browser's own parser.

You can do the same on the command line:

# Python (standard library)
python3 -m json.tool data.json

# Node.js
node -e "console.log(JSON.stringify(JSON.parse(require('fs').readFileSync(0,'utf8')),null,2))" < data.json

# jq, if installed: format, or minify with -c
jq . data.json
jq -c . data.json

Syntax validation is not schema validation

A document can be perfectly valid JSON and still be wrong for your application: a missing field, a number where a string was expected, an unknown status value. Syntax validation answers “can this be parsed?”. Schema validation answers “does this have the shape we agreed?”. For the second question, describe the expected structure with JSON Schema and check documents with a validator library in your language. Do both in production code that accepts JSON from outside.

Reading a parse error

Parsers stop at the first character they cannot accept and report its position. The reported position is where the parser noticed the problem, which is often after the actual mistake. A missing comma between two items, for example, is reported at the start of the second item. When an error points at a line that looks fine, check the end of the line before it.

Browsers describe errors differently. One may say “Unexpected token } in JSON at position 42”, another “expected double-quoted property name at line 3 column 5”. Daily Dev Tools converts these into a line and column where possible and adds a likely cause.

The mistakes that break JSON most often

Trailing commas

{"a": 1, "b": 2,} is invalid. JavaScript allows trailing commas in object literals, which is why this mistake is so common in hand-edited JSON. Remove the final comma.

Single quotes and unquoted keys

{'name': 'Ada'} and {name: "Ada"} are JavaScript, not JSON. Both keys and strings need double quotes.

Comments

Configuration files often use “JSON with comments” (JSONC) or JSON5. Standard parsers reject // and /* */. If a file needs comments, use a format that supports them deliberately and a parser that expects it, or put explanatory text in a field such as "_comment".

Unescaped characters in strings

A double quote, backslash or raw newline inside a string must be escaped. Windows paths are a frequent cause: "C:\new\folder" contains \n, which is read as a newline, and \f, which is a form feed. Write "C:\\new\\folder".

Values JSON does not have

undefined, NaN, Infinity, dates and functions do not exist in JSON. Use null, a string or a number. Dates are usually written as ISO 8601 strings, such as "2024-03-09T14:30:00Z", or as Unix timestamps.

Copying from a log or console

Text copied from a console often includes truncation markers, smart quotes from a word processor or a byte-order mark at the start. If an error points at the very first character, check for invisible characters.

Two subtle traps

Large numbers. JSON itself places no limit on number size, but JavaScript stores numbers as 64-bit floating point, which represents integers exactly only up to 9,007,199,254,740,991 (253 − 1). A 19-digit database ID parsed in JavaScript is silently rounded, and reformatting writes the rounded value back. Send such IDs as strings.

Duplicate keys. The specification says object names should be unique but does not forbid duplicates, and parsers handle them differently. Most, including JavaScript's, keep the last value. If a document has duplicates, formatting it will quietly drop the earlier ones, so find out why they exist before you rely on the output.

A checklist for clean JSON

  1. Generate JSON with a serialiser (JSON.stringify, json.dumps and so on) rather than by joining strings.
  2. Validate syntax whenever JSON is edited by hand.
  3. Validate structure with a schema at system boundaries.
  4. Use UTF-8, ISO 8601 dates and string IDs for large integers.
  5. Format for review and version control; minify, or rely on HTTP compression, for transport.