Complete Guide to JSON Formatting: Syntax, Validation & Best Practices

JSON (JavaScript Object Notation) is the most widely used data interchange format on the modern web. Whether you're building REST APIs, managing configuration files, or working with NoSQL databases, JSON is everywhere. This guide takes you from zero to confident with JSON syntax rules, formatting techniques, and common error troubleshooting.

What Is JSON?

JSON is a lightweight text-based data format originally proposed by Douglas Crockford in 2001 and standardized by the IETF as RFC 4627 (later superseded by RFC 8259). While inspired by JavaScript's object literal syntax, JSON is language-independent and supported natively by virtually every mainstream programming language.

JSON has two core structures:

• Object: An unordered collection of key-value pairs wrapped in curly braces {}
• Array: An ordered list of values wrapped in square brackets []

JSON Syntax Fundamentals

Data Types

JSON supports exactly six data types: string, number, boolean, null, object, and array.

{
  "name": "Alice Johnson",
  "age": 28,
  "isActive": true,
  "address": null,
  "skills": ["JavaScript", "Python", "Go"],
  "contact": {
    "email": "alice@example.com",
    "phone": "+1-555-0123"
  }
}

Key Name Rules

Keys in JSON must be wrapped in double quotes. This is one of the key differences between JSON and JavaScript object literals:

// ✅ Valid JSON
{ "name": "value" }

// ❌ Invalid: single quotes
{ 'name': 'value' }

// ❌ Invalid: unquoted key
{ name: "value" }

Number Rules

JSON numbers follow strict rules:

• Integers and floats are both valid: 42, 3.14, -17
• Scientific notation is supported: 1.5e10, 2.3E-4
• Leading zeros are invalid: 07 is not valid (but 0.7 is)
• Hexadecimal is not supported: 0xFF is invalid
• Infinity and NaN are not valid JSON numbers

JSON Formatting & Beautification

Formatting (also called "beautifying" or "pretty-printing") adds indentation and line breaks to make JSON human-readable. Here's how to do it in the most popular languages:

// JavaScript: pretty-print with 2-space indent
const data = { name: "Alice", scores: [95, 87, 92] };

console.log(JSON.stringify(data, null, 2));
// Output:
// {
//   "name": "Alice",
//   "scores": [
//     95,
//     87,
//     92
//   ]
// }

// Using tab indentation
console.log(JSON.stringify(data, null, "\t"));

The same operation is equally straightforward in Python:

import json

data = {"name": "Alice", "scores": [95, 87, 92]}
print(json.dumps(data, indent=2))

JSON Minification

The opposite of formatting, minification strips all unnecessary whitespace to reduce file size — ideal for network transmission:

// Minify JSON: remove indentation and newlines
JSON.stringify(data)
// Output: '{"name":"Alice","scores":[95,87,92]}'

Common JSON Errors & Troubleshooting

Here are the most frequent JSON mistakes developers make:

1. Trailing Commas

// ❌ Invalid: trailing comma after the last property
{
  "name": "Alice",
  "age": 25,   ← this trailing comma is illegal in JSON
}

2. Comments

The JSON standard does not support comments. If you need comments, consider using JSON5 or JSONC (JSON with Comments) instead.

3. Unescaped Special Characters

// ❌ Invalid: raw newlines and tabs in strings
{ "text": "line one
line two" }

// ✅ Valid: use escape sequences
{ "text": "line one\nline two" }

Characters that must be escaped in JSON strings: \", \\, \/, \b, \f, \n, \r, \t, and \uXXXX for Unicode code points.

4. Encoding Issues

JSON must be encoded in UTF-8 (per RFC 8259). Non-ASCII characters can be written directly or escaped with Unicode notation:

// Both are equivalent
{ "city": "München" }
{ "city": "M\u00fcnchen" }

JSON Validation Best Practices

Adopt these habits to catch JSON errors early:

1. Use editor extensions: VS Code, IntelliJ and other IDEs have built-in JSON validation
2. Validate API responses: Use JSON Schema to enforce data structure contracts
3. Online tools: Quickly paste and validate to pinpoint error locations
4. CI/CD integration: Add JSON validation steps to your build pipeline

JSON vs Other Formats

Understanding how JSON compares to alternatives helps you choose the right format for each use case:

• JSON vs XML: JSON is more concise and faster to parse; XML supports attributes, namespaces and comments
• JSON vs YAML: YAML is better for human-written config files; JSON is better for machine-to-machine communication. See our YAML vs JSON comparison
• JSON vs Protocol Buffers: Protobuf is a binary format — faster serialization and smaller payloads, but not human-readable

Further Reading

• Base64 Encoding & Decoding Explained — Learn how to encode binary data as Base64 inside JSON
• JWT Complete Guide — JWT payloads are Base64-encoded JSON
• YAML vs JSON Comparison — Should you use JSON or YAML for your config files?