Why are comments not allowed in JSON?

Douglas Crockford, who created the JSON format, deliberately excluded comments to prevent developers from using them for parsing directives (like SGML did), which caused interoperability problems. He wanted JSON to be a simple, unambiguous data interchange format.

How can I add documentation to a JSON file?

Common workarounds include: using a '_comment' key with a string value, using JSONC (JSON with Comments) for editor config files that support it, switching to YAML which allows comments, or keeping documentation in a separate README file.

JSONC is JSON with Comments — a superset of JSON that allows // single-line and /* */ multi-line comments. It is not standard JSON, but editors like VS Code use it for config files such as tsconfig.json and settings.json.

JSON Does Not Allow Comments – Workarounds Explained

If you add a // or /* */ comment to a JSON file and try to parse it, you get a SyntaxError. Comments are explicitly excluded from the JSON specification — this is not a parser bug or an oversight. Here is why it works this way, and what you can do about it.

Why JSON has no comments

Douglas Crockford, who designed the JSON format, removed comments intentionally. He explained that when he tried using JSON for a configuration system, people started adding parsing directives inside comments — logic that changed how the file was processed. He saw this as a mistake and stripped comments from the spec so that JSON would remain a pure, unambiguous data format with no hidden behavior.

The consequence is that JSON.parse(), and every standards-compliant JSON parser, will throw on any comment character that appears outside a string value.

// This will throw SyntaxError:
{
  // Database configuration
  "host": "localhost",
  "port": 5432 /* PostgreSQL default */
}

Workaround 1 — use a _comment key

The most portable workaround for config files you control is to add a dedicated key whose value is a documentation string:

{
  "_comment": "Database configuration for the production environment",
  "host": "localhost",
  "port": 5432
}

By convention, keys prefixed with _ or // (as a string key, not a comment) signal to human readers that the value is documentation, not data. Your application ignores the key; the JSON remains fully valid.

Workaround 2 — JSONC (JSON with Comments)

Some tools define JSONC as an extension of JSON that permits // and /* */ comments. VS Code uses JSONC for its own config files (settings.json, tsconfig.json, launch.json). If your runtime supports JSONC, you can use comments freely:

// tsconfig.json — VS Code parses this as JSONC
{
  // Emit output to the dist directory
  "compilerOptions": {
    "outDir": "./dist"
  }
}

JSONC is not interchangeable with standard JSON — standard JSON.parse() will still throw on JSONC files. Only use JSONC with tools that explicitly declare support for it.

Workaround 3 — switch to YAML for config files

If you need comments in configuration files that you maintain (Docker Compose, Kubernetes manifests, GitHub Actions), YAML is a natural fit. YAML supports # comments and is designed for human-readable config:

# Database configuration
host: localhost
port: 5432  # PostgreSQL default

If the project already uses JSON for API responses or data interchange, you can still use YAML for the config layer without conflicting with anything. See How to Convert JSON to YAML for a practical walkthrough.

Workaround 4 — keep docs in a README

For JSON data files that are shared with external systems (schemas, package.json, API payloads), the cleanest option is to document the structure in a separate README or schema file and keep the JSON itself comment-free. This avoids any parser compatibility issues.

Validating JSON after removing comments

If you inherited a JSON file that contains comments and need to clean it up, paste it into the JSON Validator. The error message will point to the exact position of the first invalid comment, making it easy to find and remove them.