If you’ve ever pasted JSON into an API request and suddenly hit a confusing parse error, there’s a good chance comments were the culprit. This usually surprises developers coming from JavaScript, YAML, or configuration files where comments are common and expected.
Many people assume JSON behaves like JavaScript objects. It looks similar, but the rules are much stricter and comments are one of the first things that break.
Short answer: No JSON does not support comments.
The official specification, RFC 8259, explicitly disallows them,
which means even a single // or /* */ makes the entire document invalid.
Why JSON Does Not Allow Comments
JSON was intentionally designed to be strict. Its purpose is reliable data exchange, not developer convenience or documentation. By keeping the format minimal, JSON behaves the same way across browsers, servers, databases, and programming languages.
Allowing comments would introduce ambiguity. Different parsers could interpret them differently, which defeats the goal of consistency. To avoid this, the specification defines a very small set of valid tokens and comments simply aren’t one of them.
In practice, this becomes a problem when developers try to “comment out” a field while debugging or copy sample payloads from blog posts that include inline notes. JSON parsers don’t ignore those lines they fail immediately.
Example: Invalid JSON with Comments
{
// User name
"name": "John",
"age": 30
}
Even though this looks harmless, the comment line makes the JSON invalid.
A strict parser will stop processing as soon as it encounters //.
This is why APIs often reject requests that appear correct at first glance.
Valid JSON Without Comments
{
"name": "John",
"age": 30
}Once the comment is removed, the JSON becomes valid and works correctly across APIs, databases, and configuration systems.
How Developers Handle Comments in Practice
Since comments are not part of the JSON standard, developers usually handle this limitation in one of a few practical ways:
- Using a dedicated
_commentordescriptionfield inside the object - Keeping documentation separate from the JSON payload
- Switching to formats like JSONC, JSON5, or YAML when comments are required
JSON also disallows other syntax features that developers commonly expect. For example, trailing commas are not allowed under RFC 8259, even though many languages permit them.
This is why many developers quickly run payloads through an online JSON formatter before sending data to production APIs.
Frequently Asked Questions
Are comments allowed in JSON?
No. According to RFC 8259, JSON does not allow comments of any kind.
Using // or /* */ makes the document invalid.
Why does JSON forbid comments?
JSON forbids comments to remain simple, predictable, and consistent across all programming languages and platforms.
If you need comments for configuration or documentation, JSON may not be the right format for that job. Formats like YAML or JSONC exist for a reason JSON simply isn’t designed for annotated data.