JSON Best Practices: Writing Clean, Efficient JSON

Consistent Naming Conventions

The two most common conventions for JSON property names are camelCase and snake_case. The most important rule is to pick one and stick with it throughout your entire API or project.

camelCase is the dominant convention in JavaScript ecosystems and is used by Google's JSON style guide. It maps naturally to JavaScript object properties, reducing the need for transformation layers.

snake_case is preferred in Python, Ruby, and many database-centric environments. If your API primarily serves Python clients or your data originates from a PostgreSQL database, snake_case reduces friction.

{ "userId": 42, "firstName": "Ada", "createdAt": "2026-04-10T12:00:00Z" }

Avoid mixing conventions in the same payload. A response that uses userId alongside last_name signals an inconsistent API and forces consumers to handle both patterns.

Use Proper Data Types

One of the most common JSON anti-patterns is wrapping numbers and booleans in strings. JSON supports distinct types for a reason: they enable clients to use values directly without parsing.

{
  "count": "15",
  "active": "true",
  "price": "29.99"
}

{
  "count": 15,
  "active": true,
  "price": 29.99
}

Stringified numbers force every consumer to call parseInt() or parseFloat(), introducing potential NaN bugs. The exception is very large integers (beyond JavaScript's Number.MAX_SAFE_INTEGER), which should be sent as strings to avoid precision loss.

Nesting Depth Guidelines

Deeply nested JSON is hard to read, hard to query, and hard to validate. As a rule of thumb, try to keep nesting to three or four levels at most. If you find yourself reaching deeper, consider flattening the structure or using references.

Instead of embedding an entire related entity, include its ID and let the client fetch it separately or use an _embedded or included top-level key (as in JSON:API). This flattened approach eliminates duplicate data and makes caching simpler.

When Deeper Nesting Is Acceptable

Configuration files, tree structures (like menus or organizational hierarchies), and AST representations naturally require deeper nesting. In API responses, however, flatten where you can. Your consumers will thank you.

Array vs Object: Choosing the Right Structure

Use arrays when you have an ordered collection of similar items. Use objects when you need key-based lookup or when items have distinct identities.

A common mistake is using an object as a map with numeric string keys like { "0": ..., "1": ..., "2": ... }. This is almost always better represented as an array. On the other hand, a lookup table mapping known string keys to values (like country codes to country names) is a natural fit for an object.

For API pagination, prefer wrapping arrays in an envelope object: { "data": [...], "meta": { "total": 100 } }. This leaves room for metadata without breaking backward compatibility.

Date Format Standards: Use ISO 8601

Always represent dates and times as ISO 8601 strings. The format 2026-04-10T14:30:00Z is unambiguous, sortable, and universally parseable across languages and platforms.

Avoid Unix timestamps in JSON payloads unless you have a specific performance reason. They are not human-readable, and the seconds-vs-milliseconds ambiguity causes frequent bugs. Avoid custom formats like MM/DD/YYYY which are locale-dependent and create parsing nightmares.

Always include timezone information. A bare 2026-04-10T14:30:00 without a Z or offset leaves interpretation to the client, which guarantees timezone-related bugs in production.

Null Handling Strategies

There are two schools of thought on null values in JSON: include them explicitly, or omit the key entirely. Both are valid, but you need to be consistent.

Explicit nulls ("middleName": null) make the schema predictable. Clients always know which fields exist, which simplifies type checking and destructuring. This approach works well with TypeScript interfaces and JSON Schema validation.

Omitting keys reduces payload size and is idiomatic in document-oriented databases like MongoDB. The downside is that clients must distinguish between "field is null" and "field does not exist," which can be a meaningful distinction in PATCH operations. Document your approach in your API specification.

Schema Validation with JSON Schema

JSON Schema lets you define the structure, types, and constraints of your JSON documents. It serves as both documentation and runtime validation, catching malformed data before it reaches your business logic.

{
  "type": "object",
  "required": ["id", "email"],
  "properties": {
    "id": { "type": "integer", "minimum": 1 },
    "email": { "type": "string", "format": "email" },
    "role": { "type": "string", "enum": ["admin", "user", "viewer"] }
  },
  "additionalProperties": false
}

Libraries like ajv (JavaScript), jsonschema (Python), and everit-json-schema (Java) all implement the JSON Schema specification. Use additionalProperties: false to catch typos in property names during development.

Performance Tips

Minification

In production APIs, always send minified JSON (no extra whitespace). The difference matters: a prettified 50 KB payload may shrink to 35 KB minified. Use JSON.stringify(data) without the space argument, and keep prettified output for debugging and logging only.

Compression

Enable gzip or Brotli compression on your server. JSON is highly compressible due to its repetitive structure. A typical JSON API response compresses by 70-90%. This is the single biggest performance win for JSON-heavy applications.

Reduce Payload Size

Use short but meaningful property names. A field called userAccountCreationTimestamp could just be createdAt. In large collections, every byte saved per record multiplies across thousands of rows. Consider implementing sparse fieldsets (letting clients request only the fields they need) using a query parameter like ?fields=id,name,email.

Common Mistakes and How to Avoid Them

• ▸Trailing commas — JSON does not allow trailing commas after the last element in an array or object. This is valid in JavaScript but will cause a parse error in JSON. Use a JSON formatter to catch these instantly.
• ▸Comments — JSON does not support comments. If you need comments in config files, consider JSON5 or JSONC (supported by VS Code), or use a dedicated _comment field.
• ▸Single quotes — JSON requires double quotes for strings and property names. Single quotes will cause a parse error.
• ▸Inconsistent enums — Define enum values as lowercase strings and document them. Mixing "Active", "ACTIVE", and "active" across endpoints is a recipe for bugs.
• ▸No versioning strategy — When your JSON schema evolves, have a plan. Use additive changes (new optional fields) when possible, and version your API when breaking changes are unavoidable.