JSON Complete Developer Guide: Formatting, Validation, and Common Pitfalls

Key Takeaways

JSON replaced XML as the dominant API format — 30–50% smaller payloads, faster parsing
8 common mistakes break JSON in production: trailing commas, single quotes, comments, undefined values
JSON Schema enables contract validation between services
For high-throughput APIs, Protobuf and MessagePack offer 3–10x better performance
JSON has no native date type — a constant source of interoperability bugs

JSON vs XML: Why JSON Won

JavaScript Object Notation was proposed by Douglas Crockford in 2001 and standardized as RFC 4627 (later superseded by RFC 8259 in 2017). By 2010, it had substantially displaced XML for web APIs. By 2024, over 80% of public APIs use JSON as their primary format.

The reasons are structural. JSON's grammar is minimal: objects, arrays, strings, numbers, booleans, and null. XML carries extensive overhead — closing tags, namespaces, attributes, processing instructions, DOCTYPE declarations — that add up to 30–50% larger payloads for equivalent data. JSON parsing requires fewer operations and produces native objects in JavaScript without transformation.

XML (verbose)

<user>
  <name>Alice</name>
  <age>28</age>
  <roles>
    <role>admin</role>
  </roles>
  <active>true</active>
</user>

JSON (compact)

{
  "name": "Alice",
  "age": 28,
  "roles": ["admin"],
  "active": true
}

The 8 Most Common JSON Mistakes (That Break Production)

1. Trailing Commas

{"name": "Alice", "age": 28,}  // ❌ Invalid JSON
{"name": "Alice", "age": 28}   // ✓ Valid

Valid in JavaScript objects and Python dicts, but forbidden in strict JSON. The spec is unambiguous on this.

2. Single Quotes Instead of Double Quotes

{'name': 'Alice'}   // ❌ Invalid JSON (JavaScript syntax)
{"name": "Alice"}   // ✓ Valid

JSON requires double quotes for all strings and all keys. Single quotes are not part of the JSON specification.

3. Comments

// This is a user object  // ❌ Comments illegal in JSON
{"name": "Alice"}
/* multi-line comment */   // ❌ Also illegal

JSON has no comment syntax by design (Douglas Crockford intentionally excluded them). Use JSONC or JSON5 if you need comments in config files.

4. Undefined, NaN, Infinity Values

{"value": undefined}    // ❌ Invalid — use null
{"value": NaN}          // ❌ Invalid — use null or omit
{"value": Infinity}     // ❌ Invalid — no valid JSON representation

These JavaScript primitives don't exist in JSON. Use null or restructure your data model.

5. No Native Date Type

{"date": "2025-12-01T08:00:00Z"}     // ISO 8601 (preferred)
{"date": "2025-12-01"}               // Date-only
{"date": 1733036400}                 // Unix timestamp (unambiguous)

JSON has no date type. Use ISO 8601 strings or Unix timestamps. Agree on the format across your team and enforce it via JSON Schema.

6. Unquoted Keys

{name: "Alice"}    // ❌ Invalid JSON (valid JS)
{"name": "Alice"}  // ✓ All keys must be double-quoted strings

7. Circular References

An object that references itself cannot be serialized to JSON — JSON.stringify() throws a TypeError. Use serializers that handle circular refs (like the flatted package) or restructure your data.

8. Large Integer Precision Loss

{"id": 9007199254740993}  // ⚠️ Beyond Number.MAX_SAFE_INTEGER
// Parsed as: 9007199254740992 in JavaScript (precision lost!)
{"id": "9007199254740993"}  // ✓ Use string for large IDs

JavaScript's 64-bit float loses precision for integers above 2^53. Twitter's API famously added string versions of tweet IDs after this caused bugs.

JSON Schema: Contract-First API Development

JSON Schema lets you define the shape, types, and constraints of your JSON data and validate documents against that definition. It's the foundation of OpenAPI/Swagger API documentation and enables both documentation and automated validation from a single source of truth.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["name", "age", "email"],
  "properties": {
    "name": { "type": "string", "minLength": 1, "maxLength": 100 },
    "age":  { "type": "integer", "minimum": 0, "maximum": 150 },
    "email": { "type": "string", "format": "email" },
    "roles": {
      "type": "array",
      "items": { "type": "string", "enum": ["admin", "user", "viewer"] }
    }
  },
  "additionalProperties": false
}

When JSON Isn't Enough: Protobuf, MessagePack, and AVIF

For internal service-to-service communication where payload size and parse speed matter, binary formats outperform JSON dramatically. Google's Protocol Buffers (Protobuf) achieves 3–10x smaller payloads than equivalent JSON and parses 2–6x faster. MessagePack is binary JSON — same data model, ~30–40% smaller, faster to parse.

For most web APIs, the ergonomics of JSON (human-readable, no schema compilation, universal tooling) outweigh these performance gains. Save Protobuf for: mobile apps where bandwidth matters, high-frequency internal microservice calls, or when you're processing millions of requests per second.

Format and Validate Your JSON

JSON Formatter & Validator

Paste any JSON to instantly format, validate, and pretty-print it. Useful for debugging API responses and configuration files.

Open JSON Formatter →