JSON Best Practices and Common Mistakes

Why Best Practices Matter

Writing valid JSON is the minimum requirement — writing good JSON is the goal. Well-written JSON is easy to read, maintain, and debug. It also reduces errors when data is shared between systems or teams. This topic covers the most important best practices and the most common mistakes beginners make when working with JSON.

Best Practice 1 — Use Meaningful Key Names

Key names should clearly describe what the value represents. Avoid using abbreviations or single-letter keys unless they are universally understood.

Poor key naming:

{
  "n": "Vijay",
  "a": 25,
  "c": "Nagpur"
}

Good key naming:

{
  "name": "Vijay",
  "age": 25,
  "city": "Nagpur"
}

Best Practice 2 — Use camelCase for Key Names

The most widely accepted convention for JSON keys in web development is camelCase — the first word is lowercase and each following word starts with an uppercase letter. This matches JavaScript naming conventions.

{
  "firstName": "Lalitha",
  "lastName": "Rajan",
  "dateOfBirth": "1998-07-14",
  "mobileNumber": "9876512345"
}

Avoid spaces, hyphens, or underscores in key names unless there is a specific reason (some APIs use snake_case like "first_name"). Stick to one convention consistently throughout a project.

Best Practice 3 — Keep JSON Structure Consistent

All records in an array should follow the same structure. Inconsistent structures cause unexpected bugs when the data is processed.

Inconsistent (problematic):

[
  { "name": "Ritu", "score": 88 },
  { "studentName": "Karan", "marks": 75 }
]

Consistent (correct):

[
  { "name": "Ritu", "score": 88 },
  { "name": "Karan", "score": 75 }
]

Best Practice 4 — Use null for Missing Values

When a value is not available or not applicable, use null instead of an empty string "" or the string "null". This makes the intent clear and avoids confusion.

{
  "name": "Anand Kumar",
  "middleName": null,
  "profilePicture": null
}

Best Practice 5 — Use Arrays for Lists of Similar Items

When storing multiple items of the same kind, always use an array. Avoid numbering keys like "item1", "item2", "item3".

Wrong approach (numbered keys):

{
  "subject1": "Math",
  "subject2": "Science",
  "subject3": "English"
}

Correct approach (array):

{
  "subjects": ["Math", "Science", "English"]
}

Best Practice 6 — Validate JSON Before Using It

Always validate JSON data from external sources (APIs, user input, files) before processing. Use JSON Schema for structured validation, and use try...catch around JSON.parse() calls to prevent crashes.

function safeParseJSON(str) {
  try {
    return JSON.parse(str);
  } catch (e) {
    console.log("Invalid JSON received.");
    return null;
  }
}

Best Practice 7 — Keep JSON Flat When Possible

Avoid deeply nesting JSON unless necessary. Excessive nesting makes data hard to read and access. If data is more than 3–4 levels deep, consider restructuring it.

Over-nested (hard to work with):

{
  "a": {
    "b": {
      "c": {
        "d": {
          "value": "too deep"
        }
      }
    }
  }
}

Flatter version (much easier to use):

{
  "value": "easy to access"
}

Best Practice 8 — Use ISO 8601 Format for Dates

JSON does not have a native date data type, so dates are stored as strings. The universally accepted format is ISO 8601: YYYY-MM-DD for dates and YYYY-MM-DDTHH:mm:ssZ for date-time.

{
  "joinDate": "2024-08-15",
  "lastLogin": "2025-01-10T09:30:00Z"
}

Avoid formats like "15/08/2024" or "August 15, 2024" as they are ambiguous and vary by region.

Common Mistake 1 — Trailing Commas

A comma after the last item in an object or array is one of the most frequent errors:

// INVALID — trailing comma
{
  "name": "Asha",
  "age": 22,
}

// VALID
{
  "name": "Asha",
  "age": 22
}

Common Mistake 2 — Single Quotes Instead of Double Quotes

// INVALID
{'name': 'Asha'}

// VALID
{"name": "Asha"}

Common Mistake 3 — Unquoted Keys

// INVALID
{name: "Asha"}

// VALID
{"name": "Asha"}

Common Mistake 4 — Adding Comments

// INVALID — JSON does not support comments
{
  // This is the user name
  "name": "Asha"
}

// VALID — no comments
{
  "name": "Asha"
}

Common Mistake 5 — Using undefined

undefined is not a valid JSON value. If a value is missing, use null instead:

// INVALID
{"score": undefined}

// VALID
{"score": null}

Common Mistake 6 — Incorrect Boolean Casing

Boolean values must be lowercase true and false. Uppercase versions are invalid:

// INVALID
{"active": True}
{"active": TRUE}

// VALID
{"active": true}

Quick Reference — Best Practices Checklist

Summary

Writing good JSON goes beyond just making it valid. Using clear key names, consistent structure, proper data types, and safe parsing practices leads to data that is reliable, maintainable, and easy for any developer to work with. Avoiding common mistakes like trailing commas, single quotes, and undefined values saves time debugging and prevents application failures. These habits form the foundation of professional, production-quality JSON usage.