Fix JSON Comments Error: RFC 8259 Standard Explained

Why JSON RFC 8259 Bans Comments (And 5 Safe Workarounds)

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.

Why RFC 8259 JSON Does Not Support 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.

Are Comments Allowed in RFC 8259?

When consulting the official specification that governs data interchange, the immediate answer is clear: the json standard does not allow comments rfc 8259 explicitly forbids their inclusion. RFC 8259 serves as the definitive engineering document for JavaScript Object Notation globally, establishing the rigid syntax boundaries that all modern parsers must obey.

During the primary architectural development of the format, standard text annotations were actively considered but ultimately rejected. As widespread adoption increased, the creator of the format, Douglas Crockford, noticed that engineers were trying to inject metadata and instructions into the file structures. The rule establishing that rfc 8259 json comments are not allowed was strictly enforced to prevent catastrophic fragmentation of the language standard.

He witnessed developers improperly using these syntax blocks to house specific parsing directives, which risked destroying interoperability entirely across different platforms and programming languages. If annotations had remained, a payload generated by a Node.js server might fail to parse correctly in a Python or Java backend because of unexpected hidden behaviors.

To clarify this historical decision permanently, Crockford issued a definitive statement explaining his engineering rationale:

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

By completely forbidding these annotations and establishing the strict RFC guidelines, the specification effectively prevents hidden parsing directives from breaking production apps. This uncompromising simplicity ensures that any valid JSON payload can be safely, securely, and uniformly parsed by any programming ecosystem without encountering unexpected token parsing errors.

Does RFC 8259 allow trailing commas in JSON?

Much like comments, trailing commas are strictly forbidden in RFC 8259 JSON. While many programming languages like JavaScript and Python comfortably allow you to leave a trailing comma after the last item in an array or dictionary, standard JSON parsers will instantly reject it. If you accidentally leave one at the end of an object or array, you will trigger a frustrating parse error that typically reads something like Trailing comma in object or Unexpected token ] in JSON. This strict rule exists to ensure absolute compatibility and predictability across all system parsers globally. If you are struggling to locate an illegal comma inside a massive data payload, you can paste your code into our JSON Formatter. Our offline tool instantly highlights invalid syntax, helping you find and remove these illegal commas without ever exposing your private data over a network.

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().

(Click "Copy Code" on the snippet below to use this in your project)

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.

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.

FAQ: RFC 8259 JSON Comments

Does JSON support comments according to RFC 8259?

No. The official RFC 8259 JSON standard does not allow comments. The creator of JSON, Douglas Crockford, explicitly removed comments from the specification to prevent parsing directives that could compromise cross-platform interoperability.

Why are comments not permitted in JSON?

Comments are not permitted in JSON because it is strictly a data-interchange format, not a configuration language. Allowing comments led to developers using them for parsing instructions, which broke compatibility between different JSON parsers.

How do I bypass the "JSON does not support comments" error?

If your compiler or linter is throwing an error, you must strip the comments using a build tool, switch your file extension to .jsonc (JSON with Comments) if your parser supports it, or convert your file to .yaml.