Can JSON Have Comments? The Complete Answer

The Short Answer

No. JSON does not support comments. Not single-line comments, not multi-line comments, not any kind of comments.

This is not an oversight. It was a deliberate design decision.

If you add a comment to a JSON file:

{
  // This is a comment
  "name": "Alice",
  "age": 30
}

Any standard JSON parser will reject this with a syntax error. The // characters are not valid JSON syntax.

Same for multi-line comments:

{
  /* This will also fail */
  "name": "Alice"
}

This is invalid JSON. It will fail in every language, every parser, every tool.

Why JSON Does Not Allow Comments

Douglas Crockford, the creator of JSON, intentionally removed comments from the specification. He explained his reasoning publicly:

"I removed comments from JSON because I saw people were using them to hold parsing directives, a practice which would have destroyed interoperability."

The concern was that if JSON supported comments, developers and tools would start embedding instructions inside comments (like parser hints, preprocessing directives, or metadata). Different tools would interpret these differently, breaking the universal compatibility that makes JSON valuable.

JSON was designed to be a pure data interchange format — nothing more. It carries data between systems. It is not a configuration language, not a programming language, and not a document format.

By keeping the specification extremely simple (no comments, no trailing commas, no single quotes), JSON remains universally parseable by every language and every platform without ambiguity.

But I Need Comments in My JSON Files

This is one of the most common frustrations developers face. You have a configuration file, you want to explain what each setting does, and JSON won't let you.

Here are your real options:

Option 1: Use a _comment Key

Add a key that describes the next value:

{
  "_comment": "Database connection settings",
  "host": "localhost",
  "port": 5432,
  "_comment_timeout": "Timeout in milliseconds",
  "timeout": 3000
}

This is technically valid JSON. The _comment keys are just regular string properties. Your application code simply ignores them.

Pros:

• valid JSON
• works with every parser
• human readable

Cons:

• pollutes the data with non-data keys
• no standard convention for the key name
• some schemas will reject unknown keys

Option 2: Use JSON5

JSON5 is an extension of JSON that allows:

• single-line comments (//)
• multi-line comments (/* */)
• trailing commas
• single-quoted strings
• unquoted keys

{
  // Database settings
  host: "localhost",
  port: 5432,
  timeout: 3000, // in milliseconds
}

Pros:

• feels natural
• supports real comments
• backwards compatible with JSON

Cons:

• not standard JSON
• requires a JSON5 parser
• not supported by most APIs

Option 3: Use JSONC (JSON with Comments)

JSONC is the format used by VS Code for its settings files (settings.json, tsconfig.json, launch.json). It allows // and /* */ comments but is otherwise standard JSON.

{
  // Enable strict mode
  "strict": true,
  /* Compiler options
     for TypeScript */
  "target": "ES2020"
}

Pros:

• supported by VS Code, TypeScript config, ESLint config
• familiar syntax
• widely used in tooling

Cons:

• not standard JSON
• won't work with JSON.parse()
• limited to specific tools that support it

Option 4: Use YAML Instead

If you need a configuration format with comments, YAML supports them natively:

# Database settings
host: localhost
port: 5432
timeout: 3000  # in milliseconds

YAML is designed for configuration. JSON is designed for data interchange. If you need comments, YAML might be the right format for your use case.

Option 5: Use a Separate Documentation File

Keep your JSON clean and put documentation in a separate file:

config.json          ← pure data, no comments
config.README.md     ← explains what each setting does

This keeps your JSON valid while providing human-readable documentation.

What About tsconfig.json?

TypeScript's tsconfig.json allows comments even though the file extension is .json. This works because TypeScript uses its own parser (JSONC parser) that strips comments before processing. It is not parsed by JSON.parse().

The same applies to:

• VS Code settings.json
• ESLint .eslintrc.json
• Various launch.json and tasks.json files

These tools use JSONC parsers internally. The files look like JSON with comments, but they are technically JSONC, not standard JSON.

Common Mistakes

Mistake 1: Adding Comments and Hoping It Works

{
  // This WILL break
  "name": "Alice"
}

JSON.parse() will throw:

SyntaxError: Unexpected token '/' at position 4

There is no setting, flag, or option to make JSON.parse() accept comments. It will always fail.

Mistake 2: Using Hash Comments

{
  # This is not valid either
  "name": "Alice"
}

Hash comments work in YAML, Python, and shell scripts. They do not work in JSON.

Mistake 3: Assuming All .json Files Are Standard JSON

Many tools use .json file extensions for files that are actually JSONC or JSON5. Just because a file has a .json extension and contains comments does not mean it is valid JSON.

If you copy a tsconfig.json with comments and try to parse it with JSON.parse(), it will fail.

Stripping Comments From JSON

If you receive a JSON file with comments and need to parse it, you need to strip the comments first.

In JavaScript:

function stripJsonComments(jsonString) {
  return jsonString
    .replace(/\/\/.*$/gm, '')     // Remove single-line comments
    .replace(/\/\*[\s\S]*?\*\//g, ''); // Remove multi-line comments
}

const cleanJson = stripJsonComments(dirtyJson);
const data = JSON.parse(cleanJson);

Warning: This simple regex approach can break if your JSON strings contain // or /* characters. For production use, use a proper JSONC parsing library.

Formatting JSON Safely

When working with JSON files — with or without comments — use a formatter that runs entirely in your browser. If your JSON contains configuration data, API responses, or internal settings, you don't want that data sent to a third-party server.

The FmtDev JSON Formatter processes everything locally. Your data never leaves your browser.

Key Takeaways

1. JSON does not support comments — this is intentional, not a bug
2. Douglas Crockford removed comments to prevent parsing directive abuse
3. Use _comment keys, JSON5, JSONC, or YAML if you need comments
4. tsconfig.json uses JSONC, not standard JSON
5. JSON.parse() will always reject comments — no exceptions
6. If you must strip comments, use a proper JSONC parser, not regex
7. Format and validate JSON locally — never send config data to online tools

Related Articles

• JSON Formatting Guide
• Fix Unexpected Token in JSON.parse
• How to Compare JSON Files
• How to Convert CSV to JSON
• JSON vs Python Dictionary: What's the Difference?