JSON Formatting Guide 2026: Syntax Rules, Data Types & Best Practices

JSON Syntax Fundamentals

JSON has a deliberately minimal syntax. The entire format is built from just two structures — objects and arrays — holding six primitive and composite data types. Together they compose every JSON document, from a single key-value pair to deeply nested configurations and API responses. Understanding these rules is the foundation for everything in our pillar JSON formatting reference.

Objects

Objects are unordered collections of key-value pairs, enclosed in curly braces. Every key must be a double-quoted string, and values may be any of the six JSON data types. Keys must be unique within the same object — duplicates silently overwrite each other in most parsers.

{
    "name": "John Smith",
    "age": 30,
    "email": "john@example.com",
    "active": true,
    "address": {
        "city": "Austin",
        "zip": "73301"
    }
}

Arrays

Arrays are ordered lists of values, enclosed in square brackets. Arrays can hold mixed types, nested objects, or even other arrays. Order is preserved, which makes arrays ideal for sequences such as log entries, paginated API results, or step lists.

{
    "fruits": ["apple", "banana", "cherry"],
    "scores": [95, 87, 92, 78],
    "mixed": [1, "two", true, null],
    "matrix": [[1, 2], [3, 4]]
}

Nesting Rules

Objects and arrays can be nested indefinitely, but most style guides recommend keeping nesting under four levels. Deep nesting hurts readability and signals that a structure should be flattened or split into separate documents. If you routinely exceed four levels, consider the techniques in our advanced JSON formatter guide for developers.

The Six JSON Data Types

Every JSON value is exactly one of six types. Knowing the constraints of each type prevents the most common encoding bugs.

Notice what JSON does not support: there is no undefined, no Date type (dates are conventionally encoded as ISO 8601 strings), no BigInt serialization standard, and no comments. For a deeper validation workflow, our JSON validator complete guide walks through schema checks and edge cases.

Formatting Standards: Indentation, Pretty-Print & Minification

JSON itself is whitespace-insensitive — a parser ignores spaces, tabs, and newlines outside of strings. Formatting is purely for humans. Two formatting modes dominate production code: pretty-print (indented, readable) and minified (whitespace removed).

Indentation: 2 Spaces vs. 4 Spaces vs. Tabs

The wider developer community has settled on a few conventions:

• 2 spaces — the dominant standard in JavaScript, TypeScript, and modern web projects (Prettier default).
• 4 spaces — common in Python, Java, and enterprise ecosystems where deeper nesting is typical.
• Tabs — technically valid, but discouraged because tab width varies by editor and can cause inconsistent diffs.

Pick one indentation style per project and enforce it via a formatter. Our JSON formatter and JSON beautifier both let you choose 2, 4, or tab indentation when pretty-printing.

Pretty-Print Example

{
  "user": {
    "id": 7,
    "name": "Ada Lovelace"
  },
  "active": true
}

Minified Example

The same document, minified for an API response, looks like this:

{"user":{"id":7,"name":"Ada Lovelace"},"active":true}

Minification typically reduces payload size by 30–60% compared to 2-space pretty-print. For high-traffic APIs, this bandwidth saving is significant. Use the JSON minifier to compress production payloads, and keep the pretty-printed version in version control for diffs and code review.

Common JSON Errors and How to Fix Them

These four mistakes cause the vast majority of JSON parse failures. Each one is silent in JavaScript source code but illegal in strict JSON.

1. Trailing Commas

JavaScript allows a comma after the last array element or object property. JSON does not.

// WRONG — trailing comma after last element
{
    "name": "John",
    "age": 30,
}

// CORRECT — no trailing comma
{
    "name": "John",
    "age": 30
}

2. Single Quotes

JSON strings must use double quotes. Single quotes are valid in JavaScript object literals but never in JSON.

// WRONG — single quotes
{'name': 'John'}

// CORRECT — double quotes only
{"name": "John"}

3. Unquoted Keys

In JavaScript, object keys may be unquoted identifiers. JSON requires every key to be a double-quoted string.

// WRONG — JavaScript style, not valid JSON
{name: "John", age: 30}

// CORRECT — all keys must be quoted
{"name": "John", "age": 30}

4. Unescaped Special Characters

Strings containing backslashes, double quotes, tabs, and newlines must be escaped:

// Characters requiring escape in JSON strings:
\"   // double quote
\\   // backslash
\/   // forward slash (optional)
\n   // newline
\t   // tab
\r   // carriage return
\uXXXX  // unicode character

Most parsers throw a single cryptic error pointing to the first illegal character. Running the document through the JSON validator first will pinpoint the exact line and column, saving hours of debugging.

Naming Conventions & Best Practices

Consistent formatting is what separates maintainable JSON from brittle JSON. Adopt these standards across your whole project:

• Consistent indentation: Use 2 or 4 spaces (never tabs) for readability in configuration files.
• Meaningful key names: Use descriptive, camelCase keys (firstName not fn or first_name) — or pick snake_case and apply it everywhere.
• Flat structures when possible: Avoid deeply nested objects — flatten when nesting exceeds 3–4 levels.
• Null vs. omission: Include keys with null values when the field is expected but empty; omit keys that are irrelevant.
• ISO 8601 dates: Always use ISO format for dates: "2026-10-22T12:00:00Z".
• Minify for production: Remove whitespace for API responses and network transfer using the JSON minifier.
• Validate before shipping: Run every JSON document through the validator in CI before merging.

For a step-by-step tool walkthrough that pairs with these standards, see our JSON formatter tool guide.

JSON vs. Other Data Formats

JSON won the API war, but it is not always the right tool. Use this comparison to pick the right format per use case.

For binary payloads — such as embedded image data or token signatures — JSON is rarely the right choice. Encoding binaries as base64 inside JSON is valid but inflates size by ~33%. For those cases, review our base64 encoder decoder guide instead.

Working with JSON in APIs

JSON is the default data format for REST and GraphQL APIs. Proper handling prevents common integration issues:

• Content-Type header: Always set Content-Type: application/json for JSON request bodies.
• Response parsing: Use native JSON parsers (JSON.parse() in JavaScript, json.loads() in Python) — never use regex or string manipulation.
• Error responses: Return errors in a consistent JSON format with error codes, messages, and details.
• Pagination: Use standard patterns like {"data": [...], "next": "...", "total": 100}.
• Versioning: Include a version field or version in the URL to evolve schemas safely.

More API integration patterns are covered in our parent developer tools guide and the developer tools category.

JSON Development Tools

Frequently Asked Questions

Related Articles

• Complete JSON Formatter & Validation Guide (Pillar)
• How to Use the JSON Formatter Tool
• JSON Validator Complete Guide
• Advanced JSON Formatter Techniques for Developers
• Base64 Encoder Decoder Guide
• Developer Tools Guide 2026
• Browse All Developer Tools