JSON Best Practices: Formatting, Naming Conventions, and Common Mistakes

JSON is universal, but that doesn't mean everyone uses it well. Bad JSON design creates bugs, parsing headaches, and API contracts you'll regret. Here are the conventions and mistakes that matter most.

Naming conventions for keys

JSON has no built-in naming convention, but your choice affects how the data feels to consumers:

camelCase: most common for JavaScript APIs and REST APIs consumed by JavaScript clients.

{ "firstName": "Alice", "lastUpdatedAt": 1745488800 }

snake_case: common in Python APIs (Django REST Framework, FastAPI), Ruby on Rails, and PostgreSQL-returned JSON.

{ "first_name": "Alice", "last_updated_at": 1745488800 }

kebab-case: rare for JSON keys — it requires quoting in JavaScript and is harder to use as object properties. Avoid.

PascalCase: used in .NET/C# ecosystems (System.Text.Json, Newtonsoft.Json) and some legacy enterprise APIs.

Pick one and be consistent. Mixing conventions in the same API is the worst outcome — consumers have to check which style each field uses.

Types: use the right one

Use the appropriate JSON type for each value — don't stringify things that should be native types:

// Wrong
{
  "count": "42",        // string instead of number
  "active": "true",     // string instead of boolean
  "items": "[]",        // string instead of array
  "timestamp": "2026-04-24T10:00:00Z"  // date as string (fine, but document it)
}

// Right
{
  "count": 42,
  "active": true,
  "items": [],
  "timestamp": 1745488800  // Unix timestamp as number
}

Dates are a grey area — JSON has no native date type. Either use Unix timestamps (integers) or ISO 8601 strings ("2026-04-24T10:00:00Z"). Document your choice. Avoid ambiguous formats like "04/24/2026" which are locale-dependent.

Null vs missing key

These are different:

// null: the field exists but has no value
{ "middleName": null }

// missing: the field does not apply (or was never included)
{}

Use null when a field is expected but currently has no value. Omit the field when it's not applicable to this object. Avoid inconsistency — if some objects include "middleName": null and others omit the key entirely, consumers need to handle both cases.

Arrays: consistent item types

Array items should have consistent types:

// Good: all items same type
{ "tags": ["javascript", "css", "html"] }
{ "scores": [98, 87, 94, 78] }

// Avoid: mixed types
{ "values": [1, "two", null, true] }

Heterogeneous arrays are technically valid JSON but force consumers to check types per item rather than parsing uniformly.

Nested vs flat: depth matters

Deeply nested JSON is hard to query and display:

// Hard to work with
{
  "user": {
    "address": {
      "location": {
        "coordinates": {
          "lat": 51.5074,
          "lng": -0.1278
        }
      }
    }
  }
}

// Easier to work with
{
  "userId": 123,
  "addressStreet": "123 Main St",
  "addressCity": "London",
  "lat": 51.5074,
  "lng": -0.1278
}

A good rule of thumb: if you need more than 3 levels of nesting, consider whether the data should be multiple related objects instead of one deeply nested object.

Pagination patterns

For paginated APIs, include enough metadata to build the next request:

{
  "data": [ ... ],
  "pagination": {
    "page": 2,
    "perPage": 20,
    "total": 150,
    "totalPages": 8,
    "hasNext": true,
    "hasPrev": true
  }
}

Or cursor-based pagination (better for large datasets):

{
  "data": [ ... ],
  "cursor": {
    "next": "eyJpZCI6MTAwfQ==",
    "prev": "eyJpZCI6ODF9"
  }
}

Error responses

Consistent error JSON makes client-side error handling predictable:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid email format",
    "field": "email",
    "status": 422
  }
}

Pick a structure and document it. Common conventions: RFC 7807 Problem Details (type, title, status, detail, instance) or Google's error format.

File size and performance

Minified JSON (no whitespace) is appropriate for API responses:

{"id":1,"name":"Alice","email":"[e-mail]"}

Pretty-printed JSON (with indentation) is appropriate for config files and logs:

{
  "id": 1,
  "name": "Alice"
}

For API responses, gzip compression handles large responses far better than formatting choices. Use Accept-Encoding: gzip and enable gzip on your server — it typically reduces JSON responses by 70–90%.

Validating and formatting JSON

When debugging API responses or config files, the JSON Formatter formats and validates JSON with syntax highlighting — paste compressed JSON, get readable output, or check whether a JSON document is valid.

---

Good JSON design is largely about consistency and using the right types. The mistakes that cause the most downstream pain are inconsistent key naming, wrong types (strings where numbers belong), and unpredictable null/missing patterns. Getting these right at the API design stage saves every consumer hours of defensive parsing code.