Handling Comments in JSON (Even Though They're Not Supported)

If you are looking for a comment syntax for JSON, the short answer is no: standard JSON does not support comments. A strict parser such as JavaScript's JSON.parse() will reject both // single-line and /* block */ comments. The confusion usually comes from tools that support JSON-like extensions such as JSONC or JSON5.

What the JSON standard actually allows

The current JSON standard is RFC 8259. Its grammar does not include comments, which means comments are not valid JSON. The RFC does leave room for permissive parsers to accept extensions, but anything claiming to produce JSON still needs to emit strict JSON.

This is invalid JSON and will fail in strict parsers:

JSON.parse(`{
  // Server port
  "port": 3000
}`);

// SyntaxError: Unexpected token '/' ...

That matters most for API payloads, exported data files, package data, and any file labeled application/json. In those cases, comments are invalid input, not a harmless convenience.

Why comments sometimes seem to work anyway

Some editors and tools intentionally support JSON-like formats for human-edited configuration files. Visual Studio Code, for example, has a jsonc mode for files such as settings.json, tasks.json, and launch.json. In that mode, line comments and block comments are allowed.

This is the distinction that usually trips people up: a tool can support comments in a JSON-like file, but that does not make comments part of JSON itself.

Choose the right format for the job

1. Use strict JSON when compatibility matters

Use strict JSON when the file is exchanged between systems, sent over an API, checked by generic validators, or consumed by unknown tooling. In those cases, compatibility matters more than authoring convenience.

2. Use JSONC for human-edited config when the tool documents support

Use JSONC when comments are part of a local config workflow and the specific tool explicitly supports it. This is common in editor or build-tool configuration, but you should still treat JSONC as a separate format rather than "JSON with a few extras."

3. Use JSON5 only when you want a looser authoring format

JSON5 supports comments, but it also allows additional syntax such as trailing commas, single-quoted strings, and unquoted object keys. That makes it convenient for humans, but even less appropriate as a drop-in replacement for standard JSON.

{
  // This is a single-line comment
  name: 'JSON5 Example',
  version: '1.0.0',
  /* This is a
     multi-line comment */
  description: 'A configuration file with comments',
  enabled: true,
}

Safe ways to document strict JSON

If you must keep the final file valid JSON, these options are safer than adding comment syntax to the JSON itself.

1. Comment-like properties

{
  "_comment": "Main application settings",
  "apiEndpoint": "https://api.example.com",
  "timeoutSeconds": 30,
  "features": {
    "_comment": "Feature flags",
    "newUi": true
  }
}

2. JSON Schema and adjacent docs

For shared data structures, JSON Schema is often the cleanest replacement for inline comments because it documents fields without polluting the JSON instance itself.

{
  "type": "object",
  "properties": {
    "theme": {
      "type": "string",
      "description": "UI theme: light, dark, or system"
    },
    "notifications": {
      "type": "boolean",
      "description": "Whether the app should send notifications"
    }
  },
  "required": ["theme", "notifications"]
}

A README beside the file is also effective when the audience is human rather than machine. This avoids turning documentation into extra JSON fields.

Author with comments, ship without them

When teams want comments during editing but strict JSON in production, the usual pattern is to author in an extended format and convert as part of the build or release process.

Do not remove comments with a naive regex. A pattern like //.* can destroy legitimate strings such as URLs.

{
  // Development endpoint
  "endpoint": "https://api.example.com/v1",
  "timeoutSeconds": 30
}

Use a real parser or a dedicated comment-stripping step for the format you chose. Treat comment removal as parsing, not as string replacement.

Common failures and what they mean