JSON Formatting and Validation: A Developer's Handbook

JSON is the lingua franca of APIs. You read it in API responses, write it in configuration files, and debug it when something breaks at 2 AM. Yet most developers learn JSON by osmosis rather than actually studying its rules — which is why a missing comma or trailing bracket can eat an hour of your day.

This guide covers everything you need to work with JSON confidently: syntax rules, common errors, formatting tools, and debugging strategies.

JSON Syntax in 60 Seconds

JSON (JavaScript Object Notation) has six data types:

Type	Example	Notes
String	"hello"	Always double quotes
Number	42, 3.14, -1	No quotes, no leading zeros
Boolean	true, false	Lowercase only
Null	null	Lowercase only
Array	[1, 2, 3]	Ordered list, mixed types OK
Object	{"key": "value"}	Unordered key-value pairs

A valid JSON document must have an object or array at the root:

{
  "name": "BoltKit",
  "version": "1.0.0",
  "tools": 10,
  "pro": true,
  "beta": null,
  "features": ["chmod", "cron", "subnet"]
}

Nesting and Structure

JSON shines when you nest objects and arrays to represent complex data:

{
  "user": {
    "id": 42,
    "name": "Paul",
    "roles": ["admin", "developer"],
    "preferences": {
      "theme": "dark",
      "notifications": {
        "email": true,
        "push": false
      }
    }
  }
}

There's no depth limit in the spec, but deeply nested JSON (5+ levels) becomes hard to read and work with. If you're designing an API, keep nesting shallow where possible.

Common JSON Errors

These are the mistakes that catch developers most often:

Trailing Commas

// INVALID — trailing comma after last item
{
  "name": "BoltKit",
  "version": "1.0.0",  ← this comma breaks it
}

// VALID
{
  "name": "BoltKit",
  "version": "1.0.0"
}

JavaScript and many languages allow trailing commas, but JSON does not. This is the single most common JSON error.

Single Quotes

// INVALID
{'name': 'BoltKit'}

// VALID
{"name": "BoltKit"}

JSON only accepts double quotes. Python developers are particularly prone to this when serialising dictionaries.

Unquoted Keys

// INVALID
{name: "BoltKit"}

// VALID
{"name": "BoltKit"}

Comments

// INVALID — JSON has no comment syntax
{
  "name": "BoltKit",  // this is not allowed
  /* neither is this */
}

// VALID — no comments possible
{
  "name": "BoltKit"
}

Other Traps

• Leading zeros — 007 is invalid; use 7
• NaN and Infinity — not valid JSON values; use null or a string
• Unescaped special characters — newlines, tabs, and backslashes inside strings must be escaped (\n, \t, \\)
• Duplicate keys — technically "allowed" by the spec but behaviour is undefined; most parsers use the last value

Pretty Printing vs Minifying

Pretty printing adds indentation and line breaks for readability. Minifying strips all whitespace for smaller payloads:

// Pretty (human-readable)
{
  "name": "BoltKit",
  "tools": 10
}

// Minified (machine-optimized)
{"name":"BoltKit","tools":10}

Pretty print for: debugging, config files, documentation, logs you read manually.

Minify for: API responses, storage, network transfer, anything parsed by machines.

Command-Line JSON Tools

jq is the Swiss Army knife for JSON on the command line:

# Pretty print
echo '{"name":"BoltKit","tools":10}' | jq .

# Extract a field
echo '{"name":"BoltKit","tools":10}' | jq '.name'
# Output: "BoltKit"

# Filter an array
cat data.json | jq '.users[] | select(.role == "admin")'

# Transform structure
cat data.json | jq '{total: (.items | length), names: [.items[].name]}'

Other Useful Commands

# Validate JSON (Python, available everywhere)
python3 -m json.tool < file.json

# Pretty print with Python
python3 -m json.tool --indent 2 < file.json

# Minify with jq
jq -c . < file.json

# Sort keys (for diffing)
jq -S . < file.json

JSON vs Other Formats

Feature	JSON	YAML	TOML	XML
Human readable	Good	Excellent	Excellent	Verbose
Comments	No	Yes	Yes	Yes
Data types	6	Many	Many	Strings only
Parsing speed	Fast	Slower	Fast	Moderate
Whitespace sensitive	No	Yes	No	No
Native in browsers	Yes	No	No	Partial
Best for	APIs, data	Config files	Config files	Documents

Use JSON for APIs and data interchange. Use YAML or TOML when you need comments or human-editable config. Use XML when you're forced to by legacy systems.

JSON Schema (Brief)

JSON Schema lets you define the structure and constraints of a JSON document:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "name": { "type": "string", "minLength": 1 },
    "age": { "type": "integer", "minimum": 0 },
    "email": { "type": "string", "format": "email" }
  },
  "required": ["name", "email"]
}

JSON Schema is invaluable for API validation, form generation, and documentation. Many API tools (OpenAPI/Swagger) use it under the hood.

Debugging Tips

• Start at the error position. JSON parsers report the character or line where parsing failed. The actual error is usually on that line or the line above (e.g., a missing comma).
• Validate incrementally. If you're building JSON by hand, validate after adding each section rather than writing the whole thing and then debugging.
• Use diff to find changes. Sort keys with jq -S and diff two JSON files to see exactly what changed.
• Check encoding. JSON must be UTF-8 (or UTF-16/32 with BOM). If you see \uFFFD or garbled characters, you have an encoding problem.
• Watch for invisible characters. Copy-pasting from word processors can introduce non-breaking spaces, smart quotes, or zero-width characters that break JSON parsers but look fine to humans.