If you’ve ever opened a configuration file ending in .json and tried to leave a note for your future self, you’ve likely discovered a frustrating truth: JSON doesn’t officially support comments.
Despite its ubiquity across APIs, web apps, and config files, JSON remains a deliberately minimal format. It was designed for machines, not humans. Yet in real-world development, humans do need to annotate — to explain schema rules, flag deprecated fields, or leave guidance for teammates. So what’s a responsible developer to do?
Let’s unpack why JSON forbids comments, and the legitimate ways to work around it.
Why JSON Has No Native Comment Syntax
JSON — short for JavaScript Object Notation — was originally designed by Douglas Crockford in the early 2000s as a lightweight data interchange format. Its strength lies in simplicity and consistency across systems.
Crockford intentionally excluded comments to avoid parsing ambiguity. His reasoning was straightforward: comments are for humans, but JSON is for machines. Including them risked breaking parsers or introducing side effects when transferring data across systems.
In short, a valid JSON file cannot contain // or /* */ comments. If you try, any standards-compliant parser will throw an error like:
SyntaxError: Unexpected token / in JSON at position ...
This makes JSON less forgiving than languages like YAML or TOML, which embrace human readability and inline documentation.
Workarounds: Documenting Without Breaking JSON
Although JSON doesn’t allow native comments, developers have adopted several safe, pragmatic strategies to include context without corrupting data.
1. The “Underscore” or “_comment” Field
The most common workaround is to add a nonfunctional field whose key indicates that it’s a comment.
{
"_comment": "This configuration controls the API server.",
"server": {
"host": "localhost",
"port": 8080
}
}
Because JSON parsers ignore unreferenced keys, this approach keeps the file valid while embedding useful context. Conventionally, developers prefix such keys with underscores to avoid collisions with real data.
However, it’s important to note that this adds extra fields to the parsed object. If your application processes every property strictly, you may need to explicitly ignore _comment keys in your code.
2. External Documentation Files
For production systems or shared configurations, external documentation is safer. Many teams maintain a companion README.md or .jsonc (JSON-with-comments) file explaining configuration options.
For example:
config.json
config.docs.md
This keeps configuration data machine-clean while preserving commentary for developers.
3. Use JSON5 or JSONC in Development
If you absolutely need comments in configuration during development, you can use JSON5 or JSONC (JSON with Comments). These are JSON supersets that extend the standard with comment syntax and trailing commas.
// This is a comment in JSONC
{
"name": "my-app",
"version": "1.0.0", // Inline comment
}
Many modern editors (like VS Code) and build tools (like Webpack) support JSONC files out of the box. Before deployment, you can convert JSONC to standard JSON using a preprocessor or parser library.
This approach offers the best of both worlds: human readability during development, and strict compliance in production.
Why It Still Matters
It might seem trivial, but comment handling in configuration files touches on a larger issue in modern development: the tension between human readability and machine precision.
JSON’s purity makes it fast, lightweight, and widely compatible — which is exactly why it powers APIs, databases, and package manifests. But for developers maintaining complex systems, clarity and communication remain essential.
Until JSON officially evolves (if ever), balancing these needs means choosing between strict compliance and practical flexibility.
The Bottom Line
You can’t comment in a .json file — at least, not in the traditional sense. But you can document intelligently. Use _comment fields for lightweight notes, external markdown files for clarity, or JSONC for development convenience.
The trick is to remember what JSON is meant to be: not a notepad, but a contract. When you respect that boundary while still leaving breadcrumbs for the next developer, you strike the right balance between clean data and clear communication.
