Common mistakes when working with JSON - and how to avoid them

JSON (JavaScript Object Notation) is a widely-used data format for transmitting structured data over the web. It's popular because of its simplicity, human readability, and compatibility with various programming languages. However, while JSON is easy to learn, many developers—especially beginners—tend to make common mistakes when working with it.

In this article, we will explore some of the most frequent JSON mistakes and offer practical tips on how to avoid them.

Mistake 1. Using Single Quotes Instead of Double Quotes

One of the most common mistakes developers make when writing JSON is using single quotes (') around keys or values, which is acceptable in many programming languages but not valid in JSON.


    {
        'name': 'John Doe',
        'age': 30
    }

Why It’s Wrong:
JSON strictly requires that all string keys and values use double quotes ("), not single quotes.

How to Avoid It:
Always use double quotes around both the keys and string values in JSON.


    {
        "name": "John Doe",
        "age": 30
    }

Tip: Use a JSON validator tool like JSONEditor to ensure your JSON syntax is correct.

Mistake 2. Trailing Commas in Arrays and Objects

Another common error is adding a trailing comma at the end of the last item in an array or object. While trailing commas are allowed in some programming languages, they are not valid in JSON.


    {
        "name": "John Doe",
        "age": 30,
    }

Why It’s Wrong:
JSON does not permit trailing commas in arrays or objects. If you include one, it will result in a parsing error.

How to Avoid It:
Ensure that there is no trailing comma after the last item in an object or array.


    {
        "name": "John Doe",
        "age": 30
    }

Mistake 3. Using Undefined Data Types (e.g., Comments or Functions)

JSON only supports a limited set of data types: strings, numbers, booleans, arrays, objects, and null. Developers sometimes mistakenly include unsupported types like functions, comments, or undefined variables.


    {
        "name": "John Doe",
        "age": 30,
        "comment": /* this is a comment */ "He is a developer"
    }

Why It’s Wrong:
Unlike JavaScript, JSON doesn’t allow functions, comments, or undefined. JSON is purely a data format, so it doesn’t support executable code or metadata like comments.

How to Avoid It:
Stick to the supported JSON data types. If you need to include comments for documentation purposes, keep them outside the JSON data or use tools designed for commenting JSON, such as JSON5 (an extension of JSON that supports comments).


    {
        "name": "John Doe",
        "age": 30
    }

Mistake 4. Improper Use of Arrays and Objects

JSON data is either an object ({}) or an array ([]). Sometimes developers confuse when to use which, resulting in improper structures, such as using an object when an array is needed, or vice versa.


    [
        "name": "John Doe",
        "age": 30
    ]

Why It’s Wrong:
This structure is incorrect because name and age should be key-value pairs inside an object ({}), not in an array. Arrays in JSON are used to represent ordered lists of values, not named properties.

How to Avoid It:
Use objects to represent key-value pairs and arrays for lists of values.


    {
        "name": "John Doe",
        "age": 30
    }

If you need a list, use an array:


    [
        "Apple",
        "Banana",
        "Orange"
    ]

Mistake 5. Incorrect Number Format

Another mistake is representing numbers in a format that JSON doesn’t support, such as including leading zeros, using NaN, or using Infinity.


    {
        "price": 0150,  // Leading zero
        "temperature": NaN,  // Not a Number
        "height": Infinity  // Infinity value
    }

Why It’s Wrong:
JSON does not allow numbers with leading zeros or special values like NaN (Not-a-Number) or Infinity. JSON only supports basic numeric formats: integers and floating-point numbers.

How to Avoid It:
Ensure that numbers are represented correctly. Do not include leading zeros, and avoid special values like NaN or Infinity.


    {
        "price": 150,
        "temperature": null,  // Use null to represent unavailable or unknown data
        "height": 1.75
    }

Mistake 6. Forgetting to Escape Special Characters in Strings

Strings in JSON can contain special characters, such as quotes or backslashes, but these need to be properly escaped. Forgetting to escape these characters can result in invalid JSON.


    {
        "message": "He said, "Hello!""
    }

Why It’s Wrong:
Unescaped double quotes within a string will break the JSON format because they’ll be interpreted as the end of the string.

How to Avoid It:
Use a backslash (\) to escape special characters within strings.


    {
        "message": "He said, \"Hello!\""
    }

Mistake 7. Invalid Use of null

Developers often misuse null in JSON, either misunderstanding its purpose or using it where another value would be more appropriate.


    {
        "name": null,
        "age": "null"
    }

Why It’s Wrong:
null in JSON represents the absence of a value, while "null" is simply a string that contains the word "null." These two are not interchangeable.

How to Avoid It:
Use null to represent the intentional absence of a value. Do not use the string "null" unless it's meant to be a literal string.


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

Mistake 8. Not Validating JSON

Some developers assume that their JSON data is valid without running it through a validator. This can lead to undetected syntax errors, especially in large datasets.

Why It’s Wrong:
Failing to validate JSON can result in runtime errors or failed API requests. It can also make debugging more difficult.

How to Avoid It:
Always validate your JSON before using it in applications or sending it over a network. You can use online tools like JSONLint or built-in validators in your code editor.

Mistake 9. Assuming JSON Data Types Map Directly to Programming Languages

Developers often assume that JSON data types (objects, arrays, strings, numbers, booleans, and null) map exactly to those in programming languages. This can lead to type mismatches.

How to Avoid It:
Understand that JSON has a limited set of data types, and programming languages may interpret these differently. Always explicitly cast or parse data when necessary to ensure the correct type is used in your code.

Conclusion

JSON is an essential format for modern web development, but it comes with a few pitfalls that can trip up even experienced developers. By following the best practices outlined above—such as using correct syntax, escaping special characters, and validating your JSON—you can avoid common mistakes and ensure your JSON data is both correct and efficient.

Remember to validate your JSON often, use proper data types, and stick to the JSON standard to avoid these errors in your projects.

By addressing these common mistakes, you can significantly improve your handling of JSON and ensure that your code works reliably across different platforms and environments.

JSON Editor

Knowledge Base

Conclusion