Can You Use Comments in JSON? (And What to Do Instead)

No — standard JSON does not support comments. The specification deliberately leaves them out, so a // or /* */ comment will cause a parse error in any strict JSON parser. If you need annotations, the common options are a "comment" key, a comment-friendly superset like JSONC or JSON5, or stripping comments before parsing.

This trips up almost everyone who edits a config file by hand. Below is exactly why comments aren't allowed, and the practical workarounds developers actually use.

Why Doesn't JSON Allow Comments?

JSON's creator, Douglas Crockford, removed comments on purpose. His reasoning: comments were being abused to carry parsing directives, which broke interoperability between parsers. By keeping JSON a pure data format with no comments, every parser behaves identically.

So this is invalid JSON and will throw an error:

{
  // the API timeout in seconds
  "timeout": 30,
  "retries": 3  /* maximum retry attempts */
}

Paste that into a strict parser (or our JSON Validator) and you'll get an "Unexpected token" error on the /.

Workaround 1: Use a "Comment" Key

The simplest portable trick is to add a normal key that holds your note. It's valid JSON everywhere because it's just data:

{
  "_comment": "timeout is in seconds; keep under the load balancer's 60s limit",
  "timeout": 30,
  "retries": 3
}

Conventions vary — _comment, //, or $comment (used by JSON Schema). The downside: your application reads these keys too, so prefix them clearly and ignore them in code.

Workaround 2: Use JSONC or JSON5

Several supersets of JSON add comments back. They aren't valid plain JSON, but many tools understand them:

JSONC ("JSON with Comments") — used by VS Code for settings.json, tsconfig.json, etc. Supports // and /* */.
JSON5 — adds comments, trailing commas, unquoted keys, and single quotes.

{
  // JSONC allows line comments
  "timeout": 30,
  "retries": 3, // and trailing commas
}

Use these only when your toolchain explicitly supports them (editors, config loaders). Never send JSONC to a public API expecting strict JSON.

Workaround 3: Strip Comments Before Parsing

If you author config with comments but your runtime needs strict JSON, remove the comments in a build step. Node's strip-json-comments package is the standard:

import stripJsonComments from "strip-json-comments";
import fs from "node:fs";

const raw = fs.readFileSync("config.jsonc", "utf8");
const config = JSON.parse(stripJsonComments(raw));

This keeps human-friendly source files while shipping clean JSON.

Workaround 4: Use YAML Instead

If your data is configuration that humans edit frequently, JSON may be the wrong format. YAML is a JSON superset that supports native # comments and is far more readable for config:

# timeout is in seconds
timeout: 30
retries: 3   # maximum retry attempts

Every JSON document is valid YAML, so migrating is low-risk. Convert between them instantly with our JSON to YAML tool, and read more in YAML vs JSON vs XML.

Which Workaround Should You Use?

Situation	Best option
Public API payloads	No comments — use a `_comment` key if you must
VS Code / editor config	JSONC
Hand-edited app config	YAML, or JSONC + strip-on-build
Documenting a schema	`$comment` (JSON Schema) or external docs

Clean Up and Validate Your JSON

If a file is throwing errors, the fastest fix is to paste it into the JSON Formatter — it pretty-prints valid JSON and pinpoints where invalid syntax (like a stray comment) breaks parsing. Use the JSON Validator to confirm it's spec-compliant, and JSON Minify to strip whitespace for production.

Frequently Asked Questions

Can you put comments in JSON? Not in standard JSON. The spec doesn't allow // or /* */, and strict parsers will reject them.

Why doesn't JSON allow comments? JSON was intentionally designed without comments to keep it a pure, interoperable data format — comments had been misused as parser directives.

What is JSONC? JSONC is "JSON with Comments," a superset used by tools like VS Code that permits // and /* */ comments. It is not valid plain JSON.

How do I add a comment-like note to JSON? Add a regular key such as "_comment": "your note". It's valid everywhere because it's just data your code can ignore.

How do I remove comments from JSON? Use a stripper like the strip-json-comments library before JSON.parse(), or paste the file into a JSON formatter that ignores or flags the comments.

Can You Use Comments in JSON? (And What to Do Instead)