NV ToolkitFormat · Validate · Convert
Guide

Comments in JSON: Why They're Forbidden and What To Do Instead

No, standard JSON does not support comments — not //, not /* */, not anything. That's a deliberate decision, not an oversight. Here's the reasoning, and the three workarounds ranked from clean to desperate.

In short

Standard JSON has no comment syntax — Douglas Crockford removed it deliberately so every parser would read JSON identically. If you control the parser, use a comment-friendly dialect like JSON5 or JSONC; if a strict JSON consumer is involved, use a throwaway "_comment" key instead, since dialects like JSON5 compile losslessly down to standard JSON when needed.

By NaveenKumar T · Software engineer · builds and maintains NV Toolkit Published 2026-06-04 2 min read

Why JSON has no comments

Douglas Crockford removed them on purpose: people were using comments to smuggle parsing directives into data, breaking interoperability — so he deleted the feature to keep JSON purely declarative. The result is that any conforming parser anywhere reads any JSON identically, which is precisely the property that made JSON universal. The cost: configuration files that humans maintain can't explain themselves.

Workaround 1: a comment-friendly dialect (the clean fix)

If you control the parser, use a dialect built for humans. JSON5 adds comments, unquoted keys, and trailing commas; JSONC (JSON-with-comments) adds just comments and trailing commas and is what VS Code uses for its own settings. Both have first-class parsers in every major language, and both compile losslessly down to standard JSON when a strict consumer needs it — our JSON5 Validator does exactly that conversion. Once you have plain JSON, running it through our JSON Formatter keeps it readable for anyone without the JSON5 tooling installed.

ApproachAdds over strict JSONBest for
JSON5Comments, unquoted keys, trailing commas, single quotesConfig you fully control
JSONCComments and trailing commas onlyEditor/tooling configs (VS Code settings, tsconfig.json)
"_comment" keyA regular string field holding the explanationStrict JSON consumers (package.json, APIs)
javascript
{
  // JSON5: comments, trailing commas, unquoted keys — all legal
  port: 8080,        // dev default; ops overrides in prod
  retries: 3,        /* keep in sync with gateway timeout */
}

Workaround 2: data-as-documentation keys

When the consumer demands strict JSON (package.json, API payloads), the convention is a throwaway key: "_comment": "why this value exists". It works everywhere because it IS data — and that's also its weakness: it pollutes the object, survives into every consumer, can collide with real keys, and tools may reorder or strip it. Acceptable for config files read by tolerant software; wrong for data crossing API boundaries.

Know your ecosystem

tsconfig.json and VS Code settings: JSONC — comment freely, it's supported. package.json: strict JSON — npm will reject comments; use the "description" field or README instead. Kubernetes/CI configs: they're YAML precisely because comments matter in ops files. Unknown consumer: assume strict, keep comments out, or maintain a commented JSON5 source and ship the compiled JSON — checking it with our JSON Validator before it ships.

How this was tested: Syntax examples were validated with the site's own parser (JSON.parse) on 2026-09-10.

Sources

  1. RFC 8259 — The JSON Data Interchange Format
  2. JSON5 Specification
  3. VS Code Docs — JSON with Comments (JSONC)

Frequently asked questions

Why does VS Code let me comment some JSON files but not others?

Files registered as JSONC (settings.json, tsconfig.json, launch.json) get comment support; files registered as plain JSON don't. It's per-file-type, not an editor-wide rule — and it mirrors what each file's real consumer accepts.

What's the difference between JSON5 and JSONC?

JSONC = JSON + comments + trailing commas; JSON5 = all of that plus unquoted keys, single quotes, multi-line strings and friendlier numbers. JSONC is the conservative choice; JSON5 the comfortable one. Both convert cleanly to strict JSON.

How do I strip comments from a JSON5/JSONC file for a strict parser?

Run it through our JSON5 Validator — valid input comes out the other side as formatted strict JSON, comments compiled away, with exact error positions if something else is wrong.

Write config with comments in the JSON5 Formatter — then convert to strict JSON with one click whenever a consumer demands it.

Use comments today

Keep working

Related tools

JSON5 Formatter

Beautify JSON5 the way it's meant to be written — unquoted keys, trailing commas and all, with real JSON5 parsing.

JSON5 Validator

Validate JSON5 with precise errors — and get the strict-JSON equivalent of your document in the same click.

JSON Formatter

Format, beautify, and validate JSON instantly in a professional VS Code-style editor — free, fast, and 100% private.

JSON Validator

Strict RFC 8259 validation with the exact line and column of every error — plus one-click repair for broken JSON.