JSON Formatting Best Practices: A Developer's Guide

Why JSON Formatting Matters

JSON (JavaScript Object Notation) is deceptively simple. Its specification fits on a single page. But that simplicity means there is room for a lot of variation in how people write it, and inconsistency in JSON formatting leads to real problems:

• Debugging difficulty: Minified or poorly indented JSON is nearly impossible to read when diagnosing API issues
• Merge conflicts: Inconsistent formatting causes unnecessary git diffs and merge conflicts
• Integration bugs: Different naming conventions between services cause silent data loss
• Validation failures: Trailing commas, single quotes, and comments are not valid JSON but are common mistakes

Indentation: 2 Spaces Is the Standard

The most widely adopted convention is 2-space indentation. This is the default used by JSON.stringify(obj, null, 2), most API documentation generators, and tools like Prettier:

{
  "user": {
    "id": 42,
    "name": "Alice",
    "roles": [
      "admin",
      "editor"
    ]
  }
}

Some teams use 4-space indentation, which is also fine as long as it is consistent. Tabs are uncommon in JSON and should be avoided. For production APIs, send minified JSON (no whitespace) to reduce payload size, and pretty-print only for human-readable output.

Naming Conventions

The three most common naming conventions for JSON keys are:

• camelCase: "firstName", "createdAt" — JavaScript ecosystem standard, used by Google JSON Style Guide
• snake_case: "first_name", "created_at" — Ruby, Python, and database-oriented APIs
• kebab-case: "first-name" — Less common, harder to work with in most languages (requires bracket notation in JS)

The most important rule is: pick one and be consistent. Mixing conventions within the same API is the worst outcome. If you are building a JavaScript-centric API, camelCase is the natural choice. If your backend is Python or Ruby, snake_case may feel more natural.

Google's JSON Style Guide recommends camelCase. AWS uses camelCase. Stripe uses snake_case. Both are valid choices as long as you are consistent.

Null Handling

JSON has a null value, and how you use it matters. There are two schools of thought:

Option 1: Include null fields explicitly

{
  "name": "Alice",
  "phone": null,
  "email": "alice@example.com"
}

This makes the schema predictable. Clients always see the same set of keys, and null clearly communicates "this field exists but has no value."

Option 2: Omit null fields entirely

{
  "name": "Alice",
  "email": "alice@example.com"
}

This produces smaller payloads. The absence of a field implies null. Many JSON libraries support this with options like omit_nil or skipNullOn.

For APIs, the first approach (explicit nulls) is generally safer because it makes the response schema self-documenting. For configuration files and internal data, omitting nulls is often cleaner.

Date and Time Formats

JSON has no native date type. Dates are represented as strings. Use ISO 8601 format — it is the universally accepted standard:

{
  "createdAt": "2026-03-16T14:30:00Z",
  "updatedAt": "2026-03-16T14:30:00+05:00",
  "expiresOn": "2026-12-31"
}

Avoid Unix timestamps as the primary representation (they are not human-readable). Avoid custom formats like "03/16/2026" (ambiguous between MM/DD and DD/MM). Always include timezone information — use Z for UTC or an explicit offset.

Nesting Depth

Deeply nested JSON becomes difficult to parse, debug, and document. As a general rule, keep nesting to 3-4 levels maximum. If you find yourself going deeper, consider flattening the structure:

// Too deep
{
  "order": {
    "customer": {
      "address": {
        "coordinates": {
          "latitude": 40.7128
        }
      }
    }
  }
}

// Better: flatten with clear naming
{
  "orderId": 123,
  "customerName": "Alice",
  "shippingLatitude": 40.7128,
  "shippingLongitude": -74.0060
}

Arrays vs. Objects

Use arrays for ordered collections of the same type. Use objects for named properties of a single entity:

// Good: array of uniform items
{
  "users": [
    {"id": 1, "name": "Alice"},
    {"id": 2, "name": "Bob"}
  ]
}

// Bad: numbered keys pretending to be an array
{
  "user1": {"name": "Alice"},
  "user2": {"name": "Bob"}
}

For API responses that return lists, always wrap the array in an object to leave room for metadata like pagination:

{
  "data": [
    {"id": 1, "name": "Alice"}
  ],
  "pagination": {
    "page": 1,
    "perPage": 20,
    "total": 142
  }
}

JSON Schema: Validate Your Structure

JSON Schema is a vocabulary for annotating and validating JSON documents. It lets you define the expected structure, types, required fields, and constraints of your JSON data:

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

JSON Schema is invaluable for API contracts, configuration validation, and automated testing. Libraries exist for every major language (Ajv for JavaScript, jsonschema for Python, etc.).

Common Mistakes to Avoid

• Trailing commas: {"a": 1, "b": 2,} is invalid JSON. JavaScript allows trailing commas, but JSON does not.
• Single quotes: {'name': 'Alice'} is not valid JSON. JSON requires double quotes for all strings and keys.
• Comments: JSON does not support comments. Use .jsonc (JSON with Comments) for config files, or add a "_comment" key if you must.
• Unquoted keys: {name: "Alice"} is valid JavaScript but invalid JSON. All keys must be double-quoted.
• Number precision: JSON numbers are IEEE 754 doubles. For IDs larger than 2⁵³, use strings: "id": "9007199254740993"
• Boolean strings: "active": "true" is a string, not a boolean. Use "active": true (no quotes).
• Encoding: JSON must be UTF-8 encoded. If you see \uFFFD replacement characters, you have an encoding mismatch.

Tools for JSON

Every developer should have these JSON tools bookmarked:

• JSON Formatter — Format, validate, and minify JSON instantly
• JSON to YAML Converter — Convert between JSON and YAML
• Diff Checker — Compare two JSON documents side by side
• jq — Command-line JSON processor for filtering and transforming data

The Bottom Line

Good JSON formatting is not about aesthetics — it is about reducing bugs, improving developer experience, and making APIs predictable. Pick a naming convention and stick with it. Use ISO 8601 for dates. Keep nesting shallow. Validate with JSON Schema. And always run your JSON through a formatter before sharing it.

For more developer tools, explore our complete tools collection — all free, all running in your browser with no data sent to any server.