Why JSON with Comments or Trailing Commas Fails

Quick Answer

Strict JSON does not allow comments, trailing commas, single-quoted strings, unquoted keys or undefined. Payloads copied from JavaScript objects, JSON5 configs or documentation can look familiar but still fail JSON.parse and API request validation.

Example Scenario

A developer copies a sample object into a request body. It has comments, trailing commas and single quotes because it came from a JavaScript file. The API rejects it with a JSON parser error, even though the object would be valid inside JavaScript source code.

Step-by-Step Explanation

1. Confirm whether the target expects strict JSON or a relaxed config format.
2. Remove comments and trailing commas.
3. Use double quotes around keys and string values.
4. Replace undefined, NaN and Infinity with valid JSON values or strings.
5. Validate the body before sending it to the API.
6. Keep examples in documentation as strict JSON when users will copy them into requests.

JSON Is Stricter Than JavaScript Objects

JSON syntax is inspired by JavaScript object notation, but it is not the same as JavaScript source code. Strict JSON requires double-quoted property names and string values. It does not allow comments, trailing commas or expressions.

This matters because many examples are written for readability in code blocks, tests or documentation. A sample that works in a JavaScript file may fail when pasted into fetch, curl or an API console.

When an API says it accepts JSON, assume strict JSON unless the documentation explicitly says otherwise.

Comments Are Not Part of JSON

Comments are useful in configuration files, but strict JSON has no comment syntax. Lines beginning with // or blocks wrapped in /* */ will break JSON.parse. Some editors and config formats accept them, which makes the failure surprising when the same text is used as an API body.

If comments are needed for human-maintained configuration, consider JSONC, JSON5, YAML or another documented format. For API payloads, remove comments before transport.

Documentation should avoid comments inside copyable JSON request bodies. Put explanations outside the payload so users do not paste invalid syntax.

Trailing Commas Are a Common Copy Bug

JavaScript object and array literals can often include trailing commas. JSON cannot. A comma after the final property or array item produces a parser error even though the structure looks normal to many developers.

Trailing commas are easy to miss in long payloads because the visual shape still feels balanced. A formatter or validator catches them immediately and points near the offending location.

If a code generator emits JSON, it should use a JSON serializer rather than manual string concatenation. Serializers do not accidentally leave trailing commas.

Single Quotes and Unquoted Keys Are Not JSON

JavaScript allows object keys without quotes in many cases and strings wrapped in single quotes. JSON requires double quotes. {'name':'Ada'} is a JavaScript object literal style, not valid JSON.

This distinction often appears when developers copy from console output, test fixtures or documentation written casually. The payload looks readable, but strict parsers reject it before the application sees any fields.

Fix the source example rather than teaching every user to translate it mentally. Copyable examples should be valid in the target tool.

Special JavaScript Values Need Conversion

undefined, NaN and Infinity are JavaScript values, not JSON values. JSON supports null, booleans, numbers, strings, arrays and objects. If a field has no value, use null or omit the field according to the API contract.

Dates also need representation. A Date object is not a JSON value by itself; serializers usually produce an ISO string. The API should document whether it expects ISO strings, Unix seconds or milliseconds.

For request examples, avoid values that require JavaScript evaluation. The body should be data, not code.

Documentation Examples Should Be Copy-Safe

Invalid JSON often enters systems through documentation. A human-friendly sample with comments and trailing commas may be readable, but users will paste it into API clients, curl commands and support tickets. If the example is meant to be copied, it should be strict JSON.

Put explanations beside the payload instead of inside the payload. If a field needs a note, describe it in text or in a table. Keeping the JSON block valid reduces support questions and parser errors.

When docs need both JavaScript and JSON examples, label them clearly. “JavaScript object” and “JSON request body” are not interchangeable labels.

What to Check Next

Paste the payload into JSON Formatter & Validator before sending it. Once the syntax is valid, then debug schema, required fields and application rules.

If the payload comes from a relaxed config file, convert it with the correct parser and then serialize it as JSON. Do not try to strip comments with fragile regexes in production request code.

When a support ticket includes invalid JSON, point to the exact syntax issue and provide a corrected minimal payload. That helps users fix the request without guessing which part was wrong.

If your API accepts payloads from humans, return parser errors that include enough location detail to be useful. A generic bad request message forces users to search the whole body for one comma or quote.

Add copy tests for documentation snippets. Every JSON request example in docs should be parsed during documentation checks so invalid examples do not ship.

If a relaxed format is truly supported, name it explicitly. Saying “JSON” while accepting JSON5-like syntax trains users to send invalid bodies to other strict APIs. Clear naming prevents examples from leaking into the wrong integration.

For SDKs, serialize request bodies from objects instead of asking users to handwrite JSON strings. That moves syntax correctness into the language serializer and leaves users to focus on field values. It also avoids support cases where users copy examples through tools that silently replace quotes or insert hidden formatting characters.

For command-line examples, test the exact shell snippet. Quoting rules can make a valid JSON object invalid once it passes through a terminal. Include examples for macOS, Linux and Windows shells when the quoting differs, because users often copy the snippet without adapting it. A verified snippet reduces parser errors before the request reaches the API and support queue during onboarding for new API users and partner teams.

Code Examples

{
  // user profile
  name: 'Ada',
  active: true,
}

{
  "name": "Ada",
  "active": true
}

const body = JSON.stringify({
  name: 'Ada',
  active: true
});

await fetch('/api/users', { method: 'POST', body });

Common Mistakes

• Pasting JavaScript object literals into JSON request bodies.
• Leaving comments inside copyable API examples.
• Keeping trailing commas from code fixtures.
• Using single quotes or unquoted keys.
• Sending undefined or NaN and expecting JSON to preserve them.

FAQ

Related Tools

Related References

Related Workflows