Can JSON Have Comments? The Complete Answer

No. The JSON specification (RFC 8259) does not support comments. Adding // or /* */ to a JSON file will cause a parse error. However, alternatives like JSONC, JSON5, and YAML do support comments and work well for configuration files.

When you just tried to add a comment to a JSON file and it broke, you probably got confused. This restriction surprises most developers because comments are fundamental to coding. But there ARE workarounds you can use right now to document your data.

Can JSON Have Comments? Why JSON Doesn't Allow Comments

You might be wondering why JSON doesn't support comments when almost every other format does. Douglas Crockford deliberately removed them from the spec during its early creation. He saw developers misusing them and decided to enforce strict rules.

His actual quote explains it perfectly: "I removed comments from JSON because I saw people were using them to hold parsing directives, a practice which would have destroyed interoperability."

Developers were essentially writing custom instructions inside comments. This meant a JSON file generated by one system could not be parsed by another system safely.

The JSON spec (RFC 8259) defines exactly what's valid: objects, arrays, strings, numbers, booleans, null. That's it. There are no tags, no metadata fields, and definitely no comments.

This strict limitation is a FEATURE not a bug. It keeps JSON simple and universal across every programming language. You never have to worry about how your parser will handle hidden directives.

Can JSON Have Comments? What Happens When You Add Comments

When you learn how to add comments to JSON, you usually assume standard JavaScript syntax will work. This seems logical since JSON is based on JavaScript object notation.

Here is a code block of JSON with // comments.

{
  // This controls the database timeout setting
  "timeout": 5000
}

When you try to parse this string, it fails instantly. The JavaScript engine does not know what to do with the slashes.

Here is the parse error it produces.

SyntaxError: Unexpected token / in JSON at position 4

You might think block comments will work better. Here is a code block of JSON with /* */ comments.

{
  /* This controls the database timeout setting */
  "timeout": 5000
}

Standard parsers will reject this and show that parse error too. If you're seeing Unexpected token / in JSON, this is why. You can read our complete guide on how to fix fixing "Unexpected token..." errors to resolve these issues.

5 Workarounds That Actually Work

You still need a way to document your configuration data. Developers have found several proven methods to handle this limitation safely. Here are five solid options.

1. Use a _comment field

The absolute simplest method is injecting a string field to act as your note. Show this example to your team.

{
  "_comment": "This controls the retry behavior",
  "maxRetries": 3,
  "timeout": 5000
}

Pros: This is purely valid JSON, so any parser handles it perfectly. You do not need to install plugins or rewrite your code to read the file.

Cons: It pollutes your data structure. Your metadata fields could conflict with real application keys if you are not careful.

2. Use JSONC (JSON with Comments)

JSONC stands for JSON with Comments. Explain what JSONC is: it is just standard JSON + // and /* */ comments.

VS Code's settings.json uses this natively. The popular tsconfig.json uses this too, which explains why you see tsconfig comments everywhere in web development. The standard file extension is .jsonc.

{
  // This controls the retry behavior
  "maxRetries": 3
}

Parsers are readily available for this format. You can use the VS Code built-in parser or the popular jsonc-parser npm package. You can paste your files into our JSON Formatter which handles JSONC correctly.

3. Use JSON5

JSON5 is an advanced superset of standard JSON. It allows comments, trailing commas, unquoted keys, and single quotes. The json comment syntax here feels exactly like normal JavaScript code.

{
  // We can drop the quotes on keys here
  maxRetries: 3,
  timeout: 5000, /* trailing comma is totally fine */
}

This format has growing adoption across modern web tools. You can process these files using the json5 npm package in Node.js. It is good for config files, NOT for APIs or network payloads.

4. Use YAML Instead

YAML is designed for human-readable configuration and supports # comments natively. It removes the need for quotes and braces entirely.

Many tools accept both JSON and YAML natively, including Docker Compose and GitHub Actions. Here is a brief example showing the same config in YAML with comments.

# This controls the retry behavior
maxRetries: 3
timeout: 5000

YAML looks much cleaner for complex configurations. You can use our YAML Converter to transform your existing data quickly.

5. Strip Comments Before Parsing

When comparing JSONC vs JSON, you might want to avoid installing new parsers. Write a preprocessing step that simply removes // and /* */ before calling JSON.parse().

Here is a simple JavaScript function (5-6 lines) that handles this cleanup.

function parseCleanJson(dirtyString) {
  const cleanString = dirtyString
    .replace(/\/\/.*$/gm, '')
    .replace(/\/\*[\s\S]*?\*\//g, '');
  return JSON.parse(cleanString);
}

This is exactly what many build tools do internally before they process configuration files.

Which Config Files Secretly Support Comments?

Many developers get confused because they see comments working in familiar files. Here are the true formats of common configurations.

| File | Comments? | Format | |---|---|---| | tsconfig.json | Yes | JSONC | | .vscode/settings.json | Yes | JSONC | | package.json | No | Strict JSON | | .eslintrc.json | No | Strict JSON (use .js instead) | | .prettierrc | No | Strict JSON | | babel.config.json | No | Strict JSON |

Remember that package.json comments will always break your node application. Keep that file strictly formatted.

The Quick Rule

When building API responses, strictly use standard JSON. You must include no comments ever in network payloads.

For config files you control entirely, use JSONC or YAML. For config files used by external tools, check if the tool supports JSONC. Many modern development environments do.

JSON not having comments is intentional and won't change. For config files, JSONC or YAML solve this completely for modern developers.

Paste your JSON into our JSON Formatter at /json-formatter to validate it. It supports both strict JSON and JSONC out of the box.