Can You Add Comments to JSON? Yes — Here's How

One of the most common frustrations when writing JSON configuration files is the lack of comment support. The JSON spec (RFC 8259) explicitly forbids any comment syntax. If you add // comment or /* comment */ to a JSON file, it will fail to parse.

Why JSON Has No Comments

JSON was designed by Douglas Crockford as a minimal data interchange format, not a configuration language. In an interview he explained: "I removed comments from JSON because I saw people were using them to hold parsing directives." The goal was simplicity and machine-to-machine communication.

Practical Workarounds

Option 1: JSONC (JSON with Comments)

JSONC is a superset of JSON that allows // single-line and /* multi-line */ comments. It is natively supported by:

• VS Code — settings.json, launch.json, and tsconfig.json all use JSONC
• TypeScript — the tsconfig.json file uses JSONC
• Prettier config files with .jsonc extension

{
  // API endpoint base URL
  "apiUrl": "https://api.example.com",
  /* Timeout in milliseconds */
  "timeout": 5000
}

Option 2: JSON5

JSON5 is another superset of JSON (used by Babel). It extends JSON to permit comments, trailing commas, and unquoted keys — making it ideal for human-authored config files. It is less widely supported than JSONC.

Option 3: A Dedicated "_comment" Key

If you must use plain .json files, a common convention is to add a "_comment" key (underscore prefix to signal it is metadata). Tools that consume your JSON will need to ignore this key.

{
  "_comment": "Production database configuration",
  "host": "db.example.com",
  "port": 5432
}

Option 4: Switch to YAML

YAML fully supports comments with #. If your use case is primarily configuration (CI/CD pipelines, Kubernetes manifests, Docker Compose), migrating to YAML is worth considering. Use our JSON to YAML Converter to make the switch instantly.

For Tool Configs: Stay with JSONC

For configuration files that are consumed by developer tools (editors, compilers, linters), JSONC is the best choice. For data exchange between services, stick to pure JSON — comments do not belong in wire formats.