ToolSink
Back to blog

JSON Formatting Explained: Syntax, Rules, and Common Pitfalls

ToolSink Team

JSON Formatting Explained: Syntax, Rules, and Common Pitfalls

JSON (JavaScript Object Notation) is the default format for API responses, config files, and NoSQL document storage — despite the name, it's fully language-agnostic, with parsing support built into essentially every modern language. Its parser is also strict: a misplaced comma or an unquoted key breaks the entire document, not just the offending line.

Why JSON replaced XML for most of this

XML requires opening and closing tags for every value, which bloats payload size and readability. JSON maps directly onto the data structures most languages already use (objects/dictionaries and arrays/lists), which means less boilerplate and smaller payloads over the network.

Core syntax

JSON is built from two structures:

  1. Name/value pairs — realized as an object, dictionary, or hash map depending on the language
  2. An ordered list of values — an array or list

Valid data types

  • String — double-quoted Unicode text: "Hello, World!"
  • Number — signed decimal, optional exponential notation (42, -3.14, 1.2e-5); no NaN or Infinity
  • Object — key-value pairs in {}, keys must be strings
  • Array — ordered values in []
  • Boolean — true or false (lowercase only)
  • Null — null (lowercase only)
{
  "firstName": "Jane",
  "lastName": "Doe",
  "age": 30,
  "isDeveloper": true
}

["Apple", "Banana", { "type": "Fruit", "name": "Cherry" }]

The rules that actually break parsers

1. Double quotes only

Single quotes and backticks are valid in JavaScript, not in JSON. Keys must also be double-quoted.

// Invalid
{ 'name': 'John', age: 25 }

// Valid
{ "name": "John", "age": 25 }

2. No trailing commas

Trailing commas after the last element are fine in modern JavaScript (and even encouraged, since they keep diffs cleaner) — but forbidden in JSON.

// Invalid
{ "fruit": "Apple", "color": "Red", }

// Valid
{ "fruit": "Apple", "color": "Red" }

3. Escaping

Quotes inside a string, backslashes, and control characters (\n, \t) need escaping; Unicode escapes (\uXXXX) are also supported.

{
  "quote": "He said, \"Hello!\"",
  "path": "C:\\Windows\\System32"
}

Best practices beyond "just valid"

  • Consistent indentation — 2 or 4 spaces is the practical standard; most editors auto-format this
  • Pick one key naming convention and stick to it — camelCase or snake_case, either is fine, but mixing them across an API is what actually causes confusion
  • Watch nesting depth — JSON allows infinite nesting, but past 4-5 levels deep, both humans and code consuming the structure start struggling. It's usually a sign the data model itself needs flattening.

Mistakes that come up repeatedly

Trying to add comments. JSON has none — no //, no /* */. If you genuinely need commented config, use JSON5/JSONC (if your parser supports it) or add a literal "_comment" key as a workaround.

Including functions or Date objects. JSON is a data format, not a programming language — dates need to be serialized as strings, and ISO 8601 ("2026-08-20T05:47:13Z") is the standard choice for interoperability across languages.

Sending undefined. Not valid JSON — use null, or omit the key entirely.

Tools worth knowing

  • Prettier — opinionated formatter, handles JSON alongside your other code files
  • jq — command-line JSON processor for filtering/transforming data in scripts
  • JSONLint or ToolSink's JSON Formatter — quick online validators that point to the exact position of a syntax error, useful when you don't want to set up tooling for a one-off check
  • IDE extensions — VS Code, IntelliJ, and WebStorm all validate/format JSON on save by default

Conclusion

JSON's strictness is the trade-off for its simplicity — no comments, no trailing commas, no ambiguity about quote style. Once the rules are memorized, most "invalid JSON" errors come down to one of a handful of repeat offenders: a trailing comma, a single-quoted string, or an unescaped character.

Back to blog