JSON Best Practices for Developers: Structure, Naming, and Common Mistakes

JSON has become the universal data interchange format for the web. REST APIs, configuration files, database storage, log files — JSON is everywhere. Yet despite how common it is, bad JSON design is also everywhere.

This guide covers the patterns and conventions that make JSON robust and maintainable.

Key Naming Conventions

The JSON specification itself doesn't enforce any naming convention, but consistency within a project (and ideally across your entire API) is critical.

Use camelCase for API Responses

The most widely adopted convention for JSON keys in REST APIs is camelCase, because JSON originated from JavaScript and JavaScript variables use camelCase:

{
  "userId": 123,
  "firstName": "Hafiz",
  "lastLoginAt": "2026-05-10T09:00:00Z"
}

snake_case is Also Common

Python-based APIs (Django, FastAPI) and many databases prefer snake_case because it matches Python's variable naming convention:

{
  "user_id": 123,
  "first_name": "Hafiz",
  "last_login_at": "2026-05-10T09:00:00Z"
}

The rule: Pick one convention and use it everywhere. Mixing camelCase and snake_case within the same API is confusing and error-prone.

Data Type Best Practices

Dates and Times: Always Use ISO 8601

Never use Unix timestamps or custom date formats in JSON. Always use ISO 8601:

{
  "createdAt": "2026-05-10T09:15:30Z",
  "birthDate": "1990-03-15",
  "eventTime": "2026-05-10T09:15:30+04:00"
}

Z means UTC. Use UTC for timestamps and localize only in the UI.

Numbers: Be Careful with Large Integers

JavaScript's Number type has precision limits — it can't accurately represent integers larger than 2^53 - 1 (approximately 9 quadrillion). IDs from databases that use 64-bit integers may exceed this.

{
  "id": "9223372036854775807"  // ✅ Safe: string for large IDs
}

{
  "id": 9223372036854775807  // ❌ Dangerous: may lose precision in JS
}

Booleans: Use true/false, Not Strings

{ "isActive": true }   // ✅ Correct
{ "isActive": "true" } // ❌ Wrong — this is a string
{ "isActive": 1 }      // ❌ Wrong — this is a number

Nullable Fields vs Missing Fields

Be intentional about the difference between null and omitting a field:

• "middleName": null — the field exists but has no value
• Omitting middleName entirely — the field is not applicable or not returned

Pick one approach per field and document it.

Structure Best Practices

Use Objects for Resources, Arrays for Collections

// Single resource ✅
{
  "user": {
    "id": 1,
    "name": "Hafiz"
  }
}

// Collection ✅
{
  "users": [
    { "id": 1, "name": "Hafiz" },
    { "id": 2, "name": "Ali" }
  ]
}

Wrap Root Arrays

Returning a root-level array is valid JSON but creates problems — you can't easily add pagination metadata, error information, or other fields later.

// ❌ Hard to extend:
[{ "id": 1 }, { "id": 2 }]

// ✅ Easy to extend:
{
  "data": [{ "id": 1 }, { "id": 2 }],
  "total": 2,
  "page": 1
}

Keep Nesting Shallow

Deep nesting makes JSON harder to read and harder to work with programmatically. As a rule of thumb, keep nesting under 3–4 levels deep.

// ❌ Too deep:
{
  "company": {
    "departments": {
      "engineering": {
        "teams": {
          "frontend": {
            "lead": { "name": "Hafiz" }
          }
        }
      }
    }
  }
}

// ✅ Flatter with IDs:
{
  "team": { "id": "frontend", "lead_id": "hafiz-123" }
}

API Response Patterns

Consistent Error Responses

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Email address is invalid",
    "field": "email"
  }
}

Use the same error structure across your entire API. Clients shouldn't need to handle different error shapes for different endpoints.

Pagination

{
  "data": [...],
  "pagination": {
    "page": 1,
    "perPage": 20,
    "total": 847,
    "totalPages": 43
  }
}

Common JSON Mistakes

1. Trailing Commas

JSON does not allow trailing commas. This is valid JavaScript but invalid JSON:

{
  "name": "Hafiz",
  "age": 30,  ← invalid trailing comma
}

2. Comments

JSON has no comment syntax. // comment and /* comment */ are invalid in JSON. Use .jsonc (JSON with Comments) format for configuration files if your tools support it.

3. Single Quotes

JSON strings must use double quotes. Single quotes are invalid:

{ 'name': 'Hafiz' }  // ❌ Invalid
{ "name": "Hafiz" }  // ✅ Valid

4. Undefined Values

undefined is not valid JSON. Use null for intentionally empty values.

Frequently Asked Questions

Is camelCase or snake_case better for JSON?

Neither is objectively better — what matters is consistency. camelCase is the norm for JavaScript and most REST APIs because JSON came from JavaScript, while snake_case is standard in Python-based APIs like Django and FastAPI. Pick whichever matches your primary language or existing codebase and apply it to every key across your entire API.

Can JSON have comments?

No. The JSON specification has no comment syntax, so // and /* */ will cause a parse error. For configuration files where you want comments, use JSONC (JSON with Comments) or JSON5 if your tooling supports them, or move explanatory notes into a separate documentation file. If you paste JSON with comments into our JSON Formatter & Validator, it will flag exactly where the invalid syntax is.

Why should large IDs be stored as strings in JSON?

JavaScript represents all numbers as 64-bit floats, which can only safely hold integers up to 2^53 - 1 (about 9 quadrillion). Database IDs from 64-bit integer columns can exceed that, and when they do, JavaScript silently rounds them — so 9223372036854775807 might become 9223372036854776000. Wrapping large IDs in quotes as strings preserves them exactly.

What is the difference between null and a missing field in JSON?

null means the field exists but has no value right now (for example, a user who hasn't set a middle name). A field that is entirely absent usually means the value is unknown, not applicable, or intentionally not returned. Decide which convention each field uses, document it, and stay consistent so clients know how to handle both cases.

Validate and Format Your JSON

Use our free JSON Formatter & Validator to:

• Validate JSON syntax and see exact error messages
• Format/beautify minified JSON for readability
• Minify formatted JSON for production
• Detect common issues like trailing commas and single quotes

Clean, validated JSON saves hours of debugging time on both the frontend and backend.