In this blog, we’ll break down the rules around comments in JSON, why comments aren't officially supported, what alternatives exist, and how to handle comments in JSON safely when needed.
What Is JSON?
JSON stands for JavaScript Object Notation. It’s a lightweight data interchange format that’s easy for humans to read and write and easy for machines to parse and generate. JSON is used extensively in web applications for transmitting data between a client and a server.
Here’s a simple JSON object:
{
"name": "Alice",
"age": 30,
"isDeveloper": true
}
It looks a lot like a JavaScript object—but with stricter rules.
Can You Use Comments in JSON?
The short answer is no.
JSON strictly adheres to its specification, RFC 8259, which does not allow comments. This means that any use of // or /* */ style comments will cause most JSON parsers to throw an error.
For example:
{
// This is a comment
"name": "Alice"
}
Or:
{
"age": 30 /* age in years */
}
Both of these examples will fail in standard JSON parsers.
Why JSON Doesn’t Support Comments
The original creator of JSON, Douglas Crockford, deliberately left comments out of the specification. His reasoning was that comments were often misused to carry metadata that should instead be part of the data itself. He also wanted to keep JSON as minimal and clean as possible.
While this choice made JSON simpler and more universal, it left developers without a native way to annotate their data structures.
Workarounds for Comments in JSON
Despite the limitations, there are some practical workarounds developers use to include comments or metadata-like explanations:
1. Add a Comment Field
One popular method is to add a dummy field to carry comment data:
{
"_comment": "This is a comment for human readers only",
"name": "Alice",
"age": 30
}
This works because _comment is just a regular key. It won’t break your parser, but you’ll need to ensure that the application reading the JSON either ignores or handles it correctly.
Pros:
- Fully valid JSON
- No parsing issues
Cons:
- Can clutter your data
- Requires filtering out comment fields during processing
- Use JSONC (JSON with Comments)
JSONC is a non-standard extension that allows comments using // and /* */. Some tools, like Microsoft’s VS Code, support JSONC files (usually with a .jsonc extension) for settings.
Example:
{
// This sets the user's name
"name": "Alice"
}
Important: JSONC is not supported by most JSON parsers and should only be used in environments where JSONC is explicitly accepted.
- Preprocess JSON with Comments
If you absolutely need to use comments but must submit valid JSON, you can preprocess the file. Some tools or build pipelines allow you to strip out comments before parsing the file.
This approach typically involves writing JSON with comments (in JSONC format) and running a script to remove them before deployment.
When You Should Use Alternatives
If you're dealing with configuration files or anything end-user-facing, consider switching to more flexible formats that support comments:
- YAML: A human-readable data format that allows comments using #.
- TOML: Used by tools like Rust’s Cargo and supports comments.
- INI: Simple and supports ; or # for comments.
Conclusion
While you can’t natively add comments in JSON, there are plenty of workarounds and best practices for documenting your data structures. Whether it’s through dummy fields, preprocessing, or switching to more flexible formats like YAML, you can still keep your JSON files clear and understandable.
If you're collaborating with others or maintaining large JSON configurations, choose the method that best balances clarity and compatibility with your tools.
Pro Tip: If your team relies heavily on JSON and documentation, consider creating a README or documentation file alongside your JSON files to explain structure, values, and expected formats.