JSON Formatting and Validation: A Complete Guide

JSON (JavaScript Object Notation) has become the lingua franca of data exchange on the web. APIs return it, configuration files use it, databases store it, and developers spend a surprising amount of time reading, writing, and debugging it. Understanding JSON thoroughly — its syntax rules, formatting conventions, and common pitfalls — makes you more productive in virtually every area of modern development.

What JSON Is and Why It Matters

JSON is a lightweight text format for structured data. It was formalized by Douglas Crockford in the early 2000s, based on a subset of JavaScript's object literal syntax. Its success comes from being simultaneously human-readable and machine-parseable across every programming language.

A JSON document is built from two structures:

• Objects: Unordered collections of key-value pairs, wrapped in curly braces { }. Keys must be double-quoted strings. Values can be any JSON type.
• Arrays: Ordered lists of values, wrapped in square brackets [ ]. Values can be any JSON type, including nested objects and arrays.

JSON supports six value types: strings (double-quoted), numbers, booleans (true/false), null, objects, and arrays. That's it — no dates, functions, comments, or undefined. This simplicity is a feature, not a limitation.

Common JSON Syntax Errors

JSON's strictness means small mistakes cause parsing failures. Here are the errors developers hit most often:

Trailing Commas

// INVALID — trailing comma after "blue"
{
  "colors": ["red", "green", "blue",]
}

// VALID
{
  "colors": ["red", "green", "blue"]
}

JavaScript allows trailing commas, but JSON does not. This is the single most common error when hand-writing JSON.

Single Quotes

// INVALID — single quotes
{'name': 'Alice'}

// VALID — double quotes only
{"name": "Alice"}

Unquoted Keys

// INVALID — unquoted key
{name: "Alice"}

// VALID
{"name": "Alice"}

Comments

JSON does not support comments of any kind — not // nor /* */. If you need comments in configuration files, consider JSONC (JSON with Comments), which tools like VS Code and TypeScript support for their config files (tsconfig.json, settings.json).

Unescaped Special Characters

Strings must escape backslashes, double quotes, and control characters:

// INVALID
{"path": "C:\Users\name"}

// VALID — escaped backslashes
{"path": "C:\\Users\\name"}

Formatting vs. Minifying

JSON can be written in two styles, and each serves a different purpose:

Formatted (prettified) JSON adds indentation and line breaks for readability:

{
  "name": "Alice",
  "age": 30,
  "skills": [
    "JavaScript",
    "Python"
  ]
}

Minified JSON strips all unnecessary whitespace:

{"name":"Alice","age":30,"skills":["JavaScript","Python"]}

Both are identical in terms of data — parsers produce the same result. The difference is purely in whitespace characters. Use formatted JSON for reading, debugging, and configuration files. Use minified JSON for network transmission and storage where every byte counts.

JSON in Practice

APIs and Data Exchange

JSON is the default response format for most REST APIs. When you call an endpoint like GET /api/users/1, the server typically returns a JSON object. Request bodies for POST and PUT operations are also usually JSON. The Content-Type: application/json header signals JSON payload in HTTP requests and responses.

Configuration Files

Many tools use JSON for configuration: package.json (Node.js), tsconfig.json (TypeScript), .eslintrc.json, and composer.json (PHP). These files are read by tools, not transmitted over networks, so readability matters more than compactness. Always keep configuration JSON formatted.

Data Storage

Databases like MongoDB store data as BSON (binary JSON), and PostgreSQL has native JSON and JSONB column types. Even when JSON isn't the primary storage format, it's often used for export/import, data migration, and backup files. When working with Base64-encoded images, JSON is frequently the transport layer.

Frequently Asked Questions