One of the most common frustrations developers face is trying to add comments to JSON files. If you've ever tried adding // comments or /* */ comments to your JSON configuration files, you've probably discovered they simply don't work. But why?

The short answer: JSON doesn't support comments. This is by design, according to the JSON specification (RFC 8259). However, there are several practical workarounds and alternatives. This guide explains why JSON lacks comments and shows you the best solutions.

Quick Navigation: Looking for a quick solution? Jump to workarounds or explore better alternatives like JSON5.

The Problem: JSON Comments Don't Work

Here's what happens when you try to add comments to a JSON file:

This Doesn't Work

{
  // This is a comment - but it will cause a JSON parse error!
  "server": "api.example.com",
  "port": 8080,
  /* This multi-line comment
     also doesn't work */
  "ssl": true
}

Error: Unexpected token / in JSON at position 4

Any JSON parser will reject this file with a syntax error. The // and/* */ comment syntax used in JavaScript, C++, and many other languages simply doesn't exist in JSON. Learn more about JSON syntax rules.

Why Doesn't JSON Support Comments?

Douglas Crockford, the creator of JSON, intentionally excluded comments from the specification. Here's why:

1. Simplicity & Interoperability

JSON was designed to be a minimal, universal data interchange format. Comments add complexity and reduce interoperability between different systems.

2. Comment Abuse Prevention

Crockford observed that developers were using comments to include parsing directives and metadata, which broke interoperability. Read his explanation in this archived post.

3. Data vs. Documentation

JSON is meant for data, not documentation. Documentation should live outside the data file (in README files, schemas, etc.).

4. Parser Efficiency

Removing comments makes JSON parsers simpler and faster. Every parser implementation can be smaller and more efficient.

JSON Comment Workarounds

While JSON doesn't support comments, there are several workarounds you can use:

Workaround 1: Use Special Keys

Add comment-like keys to your JSON objects. This is valid JSON but the keys are ignored by your application.

{
  "_comment": "Server configuration for production",
  "server": "api.example.com",
  "port": 8080,
  
  "_note": "SSL is enabled for all connections",
  "ssl": true,
  
  "database": {
    "//": "Database connection settings",
    "host": "db.example.com",
    "port": 5432
  }
}

Pros: Valid JSON, works everywhere
Cons: Clutters data, keys are part of the object

Workaround 2: External Documentation

Keep comments in a separate file or use JSON Schema to document your structure.

// config.json (clean, no comments)
{
  "server": "api.example.com",
  "port": 8080,
  "ssl": true
}

Pros: Clean JSON, proper documentation
Cons: Separate files to maintain

Workaround 3: Strip Comments Before Parsing

Write JSON with comments, then strip them before parsing. Use tools like strip-json-comments.

// JavaScript example
const stripJsonComments = require('strip-json-comments');
const fs = require('fs');

// Read JSON file with comments
const jsonWithComments = fs.readFileSync('config.json', 'utf8');

// Strip comments
const cleanJson = stripJsonComments(jsonWithComments);

// Now parse it
const config = JSON.parse(cleanJson);
console.log(config);

Pros: Write comments naturally
Cons: Extra build step, not standard JSON

Better Alternatives: JSON5, JSONC, YAML, TOML

If you have control over your data format, consider these alternatives that support comments natively:

JSON5

Recommended

JSON5 is a superset of JSON that adds features from ES5, including comments! It's perfect for config files and supports single-line and multi-line comments.

{
  // Single-line comments work!
  server: "api.example.com",  // No quotes needed for keys
  port: 8080,
  
  /* Multi-line comments
     also work perfectly */
  ssl: true,
  
  // Trailing commas are allowed
  features: [
    "authentication",
    "rate-limiting",
  ],
}

Best for: Config files, internal tools, modern projects

JSONC (JSON with Comments)

JSONC is used by VS Code for configuration files. It's regular JSON with // and /* */ comments.

{
  // VS Code settings example
  "editor.fontSize": 14,
  "editor.tabSize": 2,
  
  /* Theme configuration
     for better readability */
  "workbench.colorTheme": "Dark+",
  
  // Extensions
  "extensions.autoUpdate": true
}

Best for: VS Code extensions, Microsoft ecosystem

YAML

YAML is a human-readable data serialization format. It natively supports comments with # and is widely used for config files.

# Server configuration
server: api.example.com
port: 8080

# SSL settings
ssl: true

# Database configuration
database:
  host: db.example.com  # Production database
  port: 5432
  
# Feature flags
features:
  - authentication   # User auth
  - rate-limiting    # API rate limits

Best for: Docker, Kubernetes, CI/CD configs (GitHub Actions, GitLab CI)

TOML

TOML (Tom's Obvious, Minimal Language) is designed for config files. It's more readable than JSON and supports comments.

# Server configuration
[server]
host = "api.example.com"
port = 8080
ssl = true

# Database settings
[database]
host = "db.example.com"  # Production database
port = 5432
max_connections = 100    # Connection pool size

# Feature flags
[features]
authentication = true
rate_limiting = true

Best for: Rust projects (Cargo.toml), Python (pyproject.toml), config files

Quick Comparison Table

Format	Comments	Trailing Commas	Best Use Case
JSON	❌ No	❌ No	APIs, data exchange
JSON5	✅ Yes	✅ Yes	Config files, modern apps
JSONC	✅ Yes	✅ Yes	VS Code, Microsoft tools
YAML	✅ Yes	N/A	Docker, K8s, CI/CD
TOML	✅ Yes	N/A	Rust, Python configs

Best Practices for JSON Documentation

For APIs: Keep JSON pure. Use external API documentation (OpenAPI/Swagger).

For config files: Use JSON5, JSONC, YAML, or TOML which support comments natively.

For schemas: Use JSON Schema to document structure and validation rules.

For teams: Create a README.md or Wiki page explaining your JSON structure.

For legacy systems: Use the "_comment" key workaround or strip-comments tools.

Conclusion

While JSON doesn't support comments by design, you have several practical solutions:

•For new projects: Use JSON5, JSONC, YAML, or TOML
•For APIs: Keep JSON pure, document externally
•For legacy systems: Use comment keys or strip-comments tools
•For schemas: Use JSON Schema for documentation

Recommended: For config files, switch to JSON5. It's backward-compatible with JSON but adds comments, trailing commas, and better readability. Try our JSON Formatter to clean up your JSON files.

Comments in JSON: Why They Don't Work & Best Workarounds