Unlike formats like YAML or XML, JSON comments are not officially supported by the specification. This leads many developers to ask: Why can’t we have comments in JSON? and Are there safe workarounds?
In this blog, we’ll dive into everything you need to know about JSON comments, including why they're excluded from the spec, what alternatives exist, and how some tools manage to support them unofficially.
What Is JSON?
Before jumping into JSON comments, it’s worth understanding what JSON is. JSON stands for JavaScript Object Notation, and it was designed as a lightweight format for storing and transporting data. It is structured with:
- Objects ({}) made up of key-value pairs
- Arrays ([]) of ordered values
- Primitives like strings, numbers, booleans, and null
Here’s a basic JSON example:
{
"name": "Alice",
"age": 30,
"isDeveloper": true
}
But what if you want to leave a note for the next developer? Like explaining what "isDeveloper" is for? In most languages and formats, you'd add a comment—but not in JSON.
JSON Doesn’t Support Comments
The lack of JSON comments is by design. According to Douglas Crockford, the creator of JSON, comments were excluded from the spec to keep the format as clean and minimal as possible. His argument was that comments tend to be misused—sometimes carrying instructions or metadata that should be expressed as actual data.
From a strict parsing standpoint, comments introduce complexity. Parsers would have to recognize and ignore them, which goes against JSON’s goal of simplicity and universality.
So, per the official spec (ECMA-404, The JSON Data Interchange Standard), comments in JSON are not allowed, and any compliant parser will throw an error if it encounters them.
Can You Still Add Comments to JSON?
Technically, no—but developers have found workarounds to simulate JSON comments. Here are the most common approaches:
- Using a Comment Field
You can add a field in your JSON object that acts as a comment:
{
"_comment": "This config is for development only",
"mode": "development",
"port": 3000
}
This is valid JSON, but you have to make sure your application ignores the _comment field. It’s not actually a comment, just a regular field with no functional use.
- Using External Documentation
Instead of adding comments to your JSON file, keep a separate documentation file (like a README or .md file) where you explain the structure and purpose of each key. This keeps your JSON clean and avoids compatibility issues.
- Using JSONC (JSON with Comments)
JSONC, or "JSON with Comments", is a relaxed version of JSON used by tools like VS Code and TypeScript’s tsconfig.json. It allows:
{
// This is a comment
"compilerOptions": {
"target": "es6"
}
}
However, JSONC is not standard JSON and won’t work with standard JSON parsers. Tools that use JSONC typically convert it to valid JSON before processing.
- Preprocessing JSON Files
Some developers preprocess JSON files using scripts that strip out comments before parsing. For example:
{
// This comment will be removed by a script
"name": "App"
}
This adds complexity but allows you to keep inline documentation during development. Just be sure your build or deployment process strips the comments out before production use.
Tools That Support JSON Comments
Although JSON comments aren’t officially supported, several modern tools allow them either through custom parsers or relaxed formats:
- VS Code: Accepts JSONC for settings files
- TypeScript: Supports comments in tsconfig.json
- Webpack: webpack.config.js files are written in JS, allowing full commenting
- CommentJSON: A Python package that allows comment-friendly JSON parsing
Keep in mind that while these tools support comments, the resulting file isn't technically valid JSON. You may run into compatibility issues if the file is used in a strict parser (like a backend API or microservice that expects pure JSON).
Should You Use Comments in JSON?
If you control both the producer and consumer of the JSON file (e.g., your own app or config tool), using JSON comments or alternatives like JSONC can be convenient during development.
But if your JSON is part of an API, third-party integration, or config shared across tools—stick to the spec. Use external documentation or _comment fields to avoid errors and ensure broad compatibility.
Conclusion
While it may seem like a small limitation, the inability to use JSON comments has sparked plenty of debate among developers. The official JSON format keeps things simple and strict, which ensures consistency across systems—but also limits inline documentation.
Thankfully, workarounds like _comment fields, JSONC, and preprocessors offer practical alternatives. Understanding these options can help you maintain clean, informative config files without breaking compatibility.
If you find yourself needing comments often, consider whether another format like YAML might be better suited for your use case.
Read more on https://keploy.io/blog/community/4-ways-to-write-comments-in-json