What This Guide Covers
This reference explains how to write comments in JSON, why native comments are not part of the JSON standard, safe alternatives and widely supported workarounds, editors and validators that help enforce safe patterns, and common pitfalls to avoid. It focuses on practical, interoperable approaches you can use today while keeping JSON machine-readable and tooling-friendly.
Why JSON Does Not Support Comments Natively
JSON is a data-interchange format designed to be simple and language-agnostic. Its grammar includes only a limited set of structural tokens: braces, brackets, colons, commas, literals, numbers, strings, and whitespace. Comments were intentionally omitted to keep parsers small and unambiguous. Adding nonstandard characters or syntax that parsers do not expect can cause parse failures in strict parsers and violates most JSON Schema validations and linting rules. Although some tools allow nonstandard extensions, you should assume that adding standard-delimiter style comments inside production JSON may break portability.
Official Specification Facts
The original JSON specification (RFC 8259) and IETF standards track do not define a comment syntax. Earlier ECMA-404 editions also did not include comments. Tools that accept a comment-like construct typically do so as an extension or via preprocessing. If strict standards compliance is required, avoid in-file annotation that uses parser-specific syntax.
Common Approaches to Annotating JSON-like Files
Because strict JSON disallows comments, developers use conventions that preserve machine-readability while enabling human notes. The most common patterns are placing metadata outside the payload, using unrecognized keys, leveraging special keys, or adopting formats that support comments natively.
File-level and External Annotation
Keep JSON files clean and attach notes outside the payload. Examples include a README in the same directory, a companion Markdown file, a YAML sidecar, or a versioned change log. For build-time tooling, preprocessors can strip comments before parsing. This approach is robust because the JSON payload remains pure and portable.
Surrogate Key Patterns
Use reserved or namespaced keys that tools ignore by default. Examples include underscores (_comment, _note, _description), a meta object (_meta or __annotations), or namespace-prefixed keys (x-comment, c_comment, custom:note). If you choose this method, agree on conventions across teams and configure linters to allow these keys so they do not trigger false errors.
Format Alternatives That Support Comments
If you need in-file annotations frequently, consider formats with native comment support: YAML, TOML, JSON5, and Hjson. You can keep machine-readable JSON for transport and use a commented format for authoring, then transform at build time. This separation keeps runtimes fast and parsers simple while giving authors space for notes.
How-to: Adding Comments Using Safe Conventions
When you must embed human notes, follow a consistent, tool-aware approach. Define one pattern for your project, document it, and enforce it with configuration so comments never break pipelines.
Step-by-step Safe Pattern
- Decide whether to keep comments outside the file (recommended) or use in-file surrogate keys.
- If using surrogate keys, pick a reserved prefix such as _ or x and agree on exact names (e.g., _comment, _description).
- Add entries like { "_comment": "Do not edit manually; generated by script v1.2" }.
- Configure validators and linters to allow your chosen keys and warn on unexpected ones.
- Ensure build steps that transform or validate JSON ignore or strip comment keys if strict schema compliance is required.
Quick Comparison of Options
| Method | Portable | Readable for Authors | Requires Preprocessing | Typical Use Case |
|---|---|---|---|---|
| External Markdown/README | Yes | Yes | No | Project-level notes, change history |
| Surrogate key (e.g., _comment) | Mostly | Yes | No | Inline notes tooling will ignore |
| JSON5/Hjson/TOML | No | Yes | Yes | Authoring with rich syntax, then transform |
| Build preprocessor to strip comments | Yes | Yes
Yes Strict JSON output pipelines |
Best Practices and Pitfalls
To keep JSON robust, treat the payload as parsers will: only include characters and structures defined in the grammar unless you deliberately use a tolerant parser. Avoid embedding notes between array elements or object properties using /* */ or // unless your toolchain explicitly supports those tokens. Prefer inert keys at the top level or within a meta object to minimize collision risk. When in doubt, externalize notes rather than risk parser incompatibility.
Tooling and Validation Guidance
Modern editors and validators can help you avoid accidental parse errors. Configure your tools to either reject unknown keys or to allow specific reserved prefixes. Common setups include: enabling JSON with JSON5 in development environments, using schema-based linting to permit _fields, and adding pre-commit checks that fail on nonportable comment syntax in files destined for production APIs.
When to Use Which Approach
Choose based on audience and automation needs. For public APIs and data feeds, keep JSON clean and attach documentation externally. For configuration files consumed by a single team, agree on a clear surrogate-key policy and enforce it with shared configs. For drafts or design artifacts, use YAML/JSON5 during authoring and generate strict JSON for deployment. The right choice depends on whether the consumer is a machine first, a human first, or both.
Summary and Quick Takeaways
Because JSON has no standard comment syntax, the safest way to add notes is to place them outside the file or use agreed reserved keys such as _comment or _meta. For authoring comfort, switch to formats with native comment support and transform to JSON at build time. Define one pattern, enforce it with tooling, and keep payloads strictly parsable for maximum interoperability and long-term maintainability.