10 Common JSON Mistakes and How to Avoid Them

Introduction

JSON (JavaScript Object Notation) is the de facto standard for data interchange in web applications, APIs, and many config files. Despite its simplicity, developers frequently make mistakes that lead to hard-to-debug issues.

In this article, we’ll explore 10 common mistakes developers make with JSON, along with practical examples, debugging tips, and best practices to avoid them.

1. Missing or Extra Commas

The problem

JSON does not allow trailing commas, unlike JavaScript objects.

✅ Valid JSON:

{
  "name": "Alice",
  "age": 30
}

🚫 Invalid JSON (extra comma):

{
  "name": "Alice",
  "age": 30,
}

How to avoid

• Use JSON linters or validators (like jsonlint.com).
• Many editors (VS Code, IntelliJ) have built-in JSON validation.

2. Using Single Quotes Instead of Double Quotes

The problem

JSON requires double quotes for keys and string values.

🚫 Invalid:

{
  'name': 'Alice'
}

✅ Valid:

{
  "name": "Alice"
}

How to avoid

• Be careful when copying from JavaScript objects, which allow single quotes.
• Always run JSON through a formatter.

3. Non-String Keys

The problem

JSON keys must always be strings, unlike JavaScript objects where keys can be numbers or symbols.

🚫 Invalid:

{
  123: "number as key"
}

✅ Valid:

{
  "123": "number as key"
}

How to avoid

• Remember that JSON is purely a data format, not executable code.

4. Comments in JSON

The problem

JSON does not support comments. Developers often try to add // or /* */ comments, causing parsing failures.

🚫 Invalid:

{
  "name": "Alice" // user name
}

How to avoid

• Use external documentation or separate config files for comments.
• If you must include metadata, use descriptive keys:

{
  "name": "Alice",
  "_comment": "user name"
}

5. Improper Number Formats

The problem

JSON only allows plain numbers, no leading zeros, NaN, or Infinity.

🚫 Invalid:

{
  "zip": 01234,
  "value": NaN
}

✅ Valid:

{
  "zip": 1234,
  "value": 0
}

How to avoid

• Be careful when serializing from languages that support these special numbers.

6. Encoding Problems with Unicode

The problem

Improper escaping of special or non-ASCII characters can lead to invalid JSON.

✅ Properly escaped:

{
  "emoji": "\uD83D\uDE80"
}

How to avoid

• Always use a standard JSON serializer (like JSON.stringify in JS or json.dumps in Python).

7. Misplaced Nested Structures

The problem

Forgetting to close nested objects or arrays is common in large JSON.

🚫 Invalid:

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

✅ Valid:

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

How to avoid

• Format JSON with tools that pretty-print and highlight matching brackets.

8. Improper Boolean Values

The problem

JSON booleans must be lowercase true or false, not True, False, YES, or NO.

🚫 Invalid:

{
  "active": True
}

✅ Valid:

{
  "active": true
}

How to avoid

• Ensure data is serialized through proper JSON libraries, not string templates.

9. Huge Files Without Streaming or Chunking

The problem

Large JSON files can be memory-intensive and hard to debug.

How to avoid

• For large data, use streaming parsers (like JSONStream in Node.js or ijson in Python).
• Split big JSON arrays into line-delimited JSON (NDJSON) for easier processing.

10. Not Validating JSON Before Use

The problem

Trusting incoming JSON without validation can lead to runtime errors or security issues.

How to avoid

• Use JSON schemas (like AJV in Node or jsonschema in Python) to validate structure.

✅ Example JSON Schema:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "age": { "type": "number" }
  },
  "required": ["name", "age"]
}

Conclusion

JSON is a simple yet powerful format, but small mistakes can cause big headaches. By understanding these common pitfalls and using the right tools (linters, formatters, schemas), you can write robust, error-free JSON.

✅ Tip: Always test your JSON with tools like:

• JSONLint
• VS Code’s built-in JSON validation
• Postman for API responses

Happy debugging! 🚀