JSON Comments

JSON does not support comments. This is one of the most surprising facts for beginners who come from programming languages like JavaScript, Python, or C#. In those languages, you can write notes inside the code using // or /* */. JSON does not allow this at all.

Why JSON Has No Comments

Douglas Crockford created JSON in 2001. He intentionally removed comments from the JSON specification. His reason was straightforward: people started using comments to include parsing directives, which broke the simplicity of JSON as a pure data format.

Think of JSON like a delivery box. The box only carries items (data). It does not carry sticky notes or instructions written on the side. The sender and receiver agree on the format in advance. The box stays clean and simple.

The Official Rule

According to the JSON specification (RFC 8259), a JSON document contains only data. Any character that is not part of a valid JSON value will cause a parse error. The comment characters // and /* */ are not part of the specification.

What Happens If You Add a Comment

If you add a comment to a JSON file and then try to parse it, the parser throws an error. The file becomes invalid JSON.

Imagine a vending machine that accepts only exact coins. If you put in a button instead of a coin, the machine rejects it. A JSON parser works the same way. Any unexpected character causes rejection.

Example of Invalid JSON with a Comment

{
  // This is a user profile
  "name": "Riya",
  "age": 25
}

This JSON is invalid. The parser will throw a SyntaxError when it encounters //.

Valid JSON (No Comments)

{
  "name": "Riya",
  "age": 25
}

This is clean, valid JSON. Every parser in every programming language can read this without any problem.

How to Work Around the No-Comment Rule

Developers use several practical tricks to add notes or documentation to JSON without breaking it.

Trick 1: Use a Special Key for Notes

You can add a key like "_comment" or "note" to store your explanation as a regular string value.

{
  "_comment": "This object stores product information",
  "productName": "Wireless Mouse",
  "price": 499
}

This is valid JSON. The _comment key is ignored by your application logic, but it stays readable for humans. The underscore prefix signals to other developers that this key is just a note, not real data.

Trick 2: Use a Separate Documentation File

Keep a README.md or a separate document that explains the structure of your JSON file. This is the cleanest approach for large projects. Your JSON stays pure, and your documentation stays separate.

Trick 3: Use JSON5 Instead of JSON

JSON5 is a relaxed version of JSON that supports comments, trailing commas, and single-quoted strings. Many code editors and some configuration tools support JSON5. However, standard JSON parsers cannot read JSON5 files.

{
  // User profile
  name: "Riya",  // first name only
  age: 25,
}

This is valid JSON5, but it is not valid standard JSON.

Trick 4: Use YAML or TOML for Config Files

If you need comments in configuration files, switch to YAML or TOML. Both formats support comments natively. Many projects use YAML for config and JSON for data transfer between systems.

Real-World Diagram: How a JSON Parser Reacts

Input JSON File
      |
      v
JSON Parser reads character by character
      |
      +---> Valid character? --> Continue reading
      |
      +---> Comment found (//) --> STOP. Throw SyntaxError.
      |
      +---> End of file with valid data --> Return parsed object

This flow shows why a comment immediately breaks the parsing process. The parser does not skip comments. It treats them as unknown characters and stops.

Tools That Ignore Comments

Some tools and environments strip comments before parsing. For example:

• VS Code's tsconfig.json and settings.json files allow comments because VS Code uses its own extended parser called JSONC (JSON with Comments).
• Node.js configuration files like jest.config.json sometimes support a JSONC format.
• Webpack and other build tools may accept relaxed JSON in their config files.

These are special environments. Standard JSON parsers — like JSON.parse() in JavaScript or json.loads() in Python — do not accept comments.

JSONC: JSON with Comments

JSONC stands for JSON with Comments. It is not an official standard, but it is widely used in developer tools. The file extension is .jsonc. VS Code uses JSONC for its own settings files.

If you open VS Code's settings.json file, you can add // comments and VS Code understands them. But if you send that file to a REST API or try to parse it with JSON.parse(), it will fail.

Best Practices for JSON Documentation

• Never add comments to JSON files that will be parsed programmatically.
• Use the "_comment" key trick only for human-readable config files that your own application will ignore.
• Use JSON Schema to formally document the structure and meaning of each field.
• Write separate documentation for any JSON-based API or data format.
• Use JSONC only in environments that explicitly support it, like VS Code settings.

Quick Summary

JSON has no comment support by design. This keeps JSON simple and universally parseable. If you need comments, use a workaround like the _comment key, a separate documentation file, or switch to a format like JSONC or YAML. Always know which environment you are working in before adding any comment-like content to a JSON file.