In our last session, you learned how to read and interpret valid JSON, navigating through nested objects and arrays to find specific pieces of data. Now, we'll tackle the inevitable next step in a support engineer's workflow: dealing with data that isn't valid. When an integration fails or a customer reports an error, one of the most common culprits is a malformed JSON payload.
Today's lesson is dedicated to helping you identify and fix common syntax errors in malformed JSON payloads. This is a critical, hands-on troubleshooting skill that you'll use constantly when diagnosing issues with API calls. We'll explore why JSON is so strict with its rules and then build a mental checklist of the most frequent errors you'll encounter.
The Why Behind the "What": JSON's Strict Syntax
You might wonder why JSON is so much stricter than, say, a JavaScript object. The reason is interoperability. JSON was designed to be a universal language for data exchange, easily understood by any programming language—from Python on a server to JavaScript in a browser or even a Java-based legacy system. This strictness eliminates ambiguity. A comma, a quote, or a brace always means the same thing, ensuring that data sent from one system can be reliably parsed by another.
Many errors arise when data is copied from other formats or manually edited. A developer might copy a Python dictionary, or you might copy an object from a JavaScript console log, and inadvertently introduce syntax that is valid in the source language but invalid in JSON.
A Field Guide to Common JSON Errors
When an API call fails with a "Bad Request" or "Parsing Error," the problem is often a simple syntax mistake in the JSON payload. Let's look at the most common offenders. Many of these are highlighted in the infographic below, which serves as a great visual summary.
To get a systematic breakdown of these issues, we'll use a detailed guide from JSONLint, an online tool you'll find invaluable for this kind of work.
Common JSON Mistakes and How to Avoid Them | JSONLint
This article from JSONLint is an excellent field guide for diagnosing broken JSON. It provides clear "Wrong" vs. "Correct" examples that make it easy to spot the differences.
Please read the following sections to build your error-spotting skills. In the Syntax Errors section, review the first five items, which are the most frequent culprits: Trailing Commas, Single Quotes, Unquoted Keys, Comments, and Missing Commas. Next, in the Data Type Errors section, focus on the two most common language-specific mistakes: Using undefined (from JavaScript) and Wrong Boolean/Null Case (often from Python). Finally, under String Errors, understand how to handle special characters by reading about Unescaped Special Characters and Multi-line Strings. After reading, take a moment to look at the Quick Reference table. This is a perfect summary to keep in mind.
As you can see from the reading, most JSON errors fall into a few simple categories. Being able to quickly scan a payload for these specific mistakes is a powerful troubleshooting technique.
Hands-on Exercise: Debugging API Payloads
Now it's time to put your new knowledge into practice. Below are five malformed JSON payloads, similar to what you might see from your hotel PMS integrations. Your task is to identify the error in each one and fix it.
For a real-world experience, I recommend copying each snippet and pasting it into an online validator like JSONLint. Its error messages will point you in the right direction, just as a good tool would in your day-to-day work.
Snippet 1: A failed booking creation
The system rejected this payload, intended to create a new booking.
{
"bookingId": "BK-TEMP-001",
"channel": "Expedia",
"status": "pending",
"primaryGuest": {
"firstName": "Jane",
"lastName": "Doe",
"email": "jane.doe@example.com",
},
}
Snippet 2: A guest profile update from a partner
This update for a guest's preferences failed to parse.
{
'guestId': "G-9876",
notes: "VIP Guest. Prefers a quiet room away from the elevator."
}
Snippet 3: A rate update from the pricing engine
The pricing engine sent this update, but the PMS couldn't process it.
{
"ratePlanId": "BAR-FLEX",
"isAvailable": True, // Make sure this is active for the weekend
"rates": [
{ "date": "2024-11-01", "price": 250.00 },
{ "date": "2024-11-02", "price": 275.00 }
]
}
Snippet 4: An availability check for multiple room types
This request to check room availability returned an error.
{
"propertyId": "PROP-99",
"checkInDate": "2024-12-20",
"checkOutDate": "2024-12-22",
"roomTypeIds": [
"DLX-KNG"
"STD-TWN"
]
}
Snippet 5: A note added to a reservation
A front-desk agent tried to add a note containing a file path, which caused a system error.
{
"note": "Guest reported issue with in-room safe. See incident report at C:\Docs\Incidents\IR-453.docx"
}
Once you've tried fixing them, check your work against the solutions below.
View Solutions
Solution 1: Trailing Commas
The primaryGuest object and the root object both had a trailing comma after their last property. JSON forbids this.
Corrected Snippet:
{
"bookingId": "BK-TEMP-001",
"channel": "Expedia",
"status": "pending",
"primaryGuest": {
"firstName": "Jane",
"lastName": "Doe",
"email": "jane.doe@example.com"
}
}
Solution 2: Single Quotes and Unquoted Keys
JSON requires all keys to be strings enclosed in double quotes. The original used single quotes for guestId and no quotes at all for notes.
Corrected Snippet:
{
"guestId": "G-9876",
"notes": "VIP Guest. Prefers a quiet room away from the elevator."
}
Solution 3: Wrong Boolean Case and Comments
The value for isAvailable was True (uppercase T), which is valid in Python but not JSON. The correct JSON value is true (lowercase). Additionally, standard JSON does not allow comments (//).
Corrected Snippet:
{
"ratePlanId": "BAR-FLEX",
"isAvailable": true,
"rates": [
{ "date": "2024-11-01", "price": 250.00 },
{ "date": "2024-11-02", "price": 275.00 }
]
}
Solution 4: Missing Comma in an Array
The items in a JSON array must be separated by commas. The comma between "DLX-KNG" and "STD-TWN" was missing.
Corrected Snippet:
{
"propertyId": "PROP-99",
"checkInDate": "2024-12-20",
"checkOutDate": "2024-12-22",
"roomTypeIds": [
"DLX-KNG",
"STD-TWN"
]
}
Solution 5: Unescaped Special Characters
The backslash (\) is a special escape character in JSON strings. To represent a literal backslash, you must escape it with another backslash (\\).
Corrected Snippet:
{
"note": "Guest reported issue with in-room safe. See incident report at C:\\Docs\\Incidents\\IR-453.docx"
}
Key Takeaways
- JSON is strict for reliability: Its rigid syntax ensures data can be exchanged between different systems without ambiguity.
- Most errors are simple: The most common issues are related to commas (trailing or missing), quotes (single vs. double, unquoted keys), and language-specific values (e.g.,
Truevs.true). - Validators are your best friend: When you suspect a JSON error, the fastest way to confirm and locate it is by using a tool like an online validator or the built-in linter in your code editor or Postman.
- Context is key: Errors often appear when data is copied from a format with more lenient syntax, like a JavaScript object or a Python dictionary.
Next Steps
You can now read valid JSON and debug invalid JSON. You have a solid handle on the most common data format for APIs. In the next lesson, we will explore XML (eXtensible Markup Language). We will learn to read its structure and then compare it with JSON, giving you a complete picture of the two dominant data formats used in modern integrations.