Understanding Comments in JSON

Key Takeaways

1. JSON does not natively support comments due to its design for pure data interchange.
2. Developers use workarounds like _comment fields or preprocessors (e.g., JSONC).
3. For configuration use cases, consider formats like YAML that support comments.

JavaScript Object Notation (JSON) is one of the most widely used data formats for data interchange between servers and web applications. It's lightweight, easy to read, and language-independent. However, one of the most common points of confusion—especially for developers used to formats like XML or programming languages like JavaScript—is the absence of support for comments in JSON.

Why JSON Doesn't Support Comments

JSON was originally specified by Douglas Crockford with simplicity and data interchange in mind. According to the official JSON specification (RFC 8259), comments are not permitted in JSON. The rationale is that JSON is meant to be a pure data format, not a configuration language. Including comments could lead to non-interoperability issues across parsers.

Douglas Crockford himself has said that he deliberately removed comment support to prevent developers from abusing JSON as a configuration language where comments might be used to store non-data content.

Workarounds and Alternatives

Even though JSON doesn’t allow traditional comments like // or /* */, developers have come up with creative (though non-standard) workarounds when comments are necessary.

1. Use a Special Field for Comments

You can use a custom key (like _comment) to simulate a comment:

{
  "name": "ChatGPT",
  "_comment": "This is a comment about the name field",
  "language": "English"
}

Pros:

• Allows human-readable notes.
• Doesn’t break JSON parsers.

Cons:

• Adds extra fields that may interfere with applications not expecting them.
• Can bloat the data unnecessarily.

2. Strip Comments Before Parsing

Some development tools or build pipelines allow JSON files with comments and strip them before parsing. For example, tools like json5, comment-json, or JSONC (JSON with Comments) allow you to write comments in files but output clean JSON.

// This is a comment
{
  "enabled": true
}

However, you must ensure that the parsing environment supports this preprocessing step.

When You Might Need Comments

• Configuration files: Projects like VSCode or TypeScript use JSONC (JSON with Comments) for settings files (settings.json, tsconfig.json) to include comments.
• Documentation purposes: When sharing examples or API schemas, temporary comments can clarify structure.

Best Practices

• Avoid relying on comments in production JSON files.
• If comments are necessary, use preprocessing tools or include metadata in separate documentation.
• For configuration files, consider using formats that support comments natively, like YAML or TOML.

Conclusion

JSON’s strict stance against comments may seem limiting at first, but it aligns with its purpose as a data exchange format. While workarounds exist, they should be used cautiously to maintain compatibility and clarity. When comments are essential, adopting tools that support JSONC or choosing more flexible formats may be the best solution.

FAQs

Why were comments excluded from the JSON format?

To keep JSON simple and ensure consistent data parsing across platforms.

Can I include comments in my JSON files using standard syntax?

No, standard JSON parsers will reject files with comments like // or /* */.

What is a safe method to include human-readable notes in JSON?

Use a custom key like _comment, but avoid it in production data.

We are Leapcell, your top choice for hosting backend projects.

Leapcell is the Next-Gen Serverless Platform for Web Hosting, Async Tasks, and Redis:

Multi-Language Support

• Develop with Node.js, Python, Go, or Rust.

Deploy unlimited projects for free

• pay only for usage — no requests, no charges.

Unbeatable Cost Efficiency

• Pay-as-you-go with no idle charges.
• Example: $25 supports 6.94M requests at a 60ms average response time.

Streamlined Developer Experience

• Intuitive UI for effortless setup.
• Fully automated CI/CD pipelines and GitOps integration.
• Real-time metrics and logging for actionable insights.

Effortless Scalability and High Performance

• Auto-scaling to handle high concurrency with ease.
• Zero operational overhead — just focus on building.

Explore more in the Documentation!

Follow us on X: @LeapcellHQ