Does JSON Support Comments? | What Breaks And Why

That catches a lot of people the first time they edit a config file. JSON looks close to JavaScript object syntax, so adding a short note beside a setting feels normal. Then the parser throws an error, and the whole file stops loading.

The reason is simple: JSON was kept small on purpose. The format allows objects, arrays, strings, numbers, booleans, and null. That’s it. Comments never made it into the grammar, so a strict parser has no legal way to accept them.

If you only need the direct answer, stop here: plain .json files should be treated as comment-free. If you need notes for humans, there are safer ways to do it without breaking tools.

Why Plain JSON Rejects Comments

The official JSON spec defines a tight set of tokens and structures. Whitespace is allowed in a few places. Comments are not. That means a parser reading standard JSON will accept spaces, tabs, line breaks, arrays, and objects, but not JavaScript-style notes.

This strictness is one reason JSON became popular for data exchange. Two systems can pass the same file around and expect the same shape, with fewer edge cases. A parser does not need side rules for comment stripping before it reads the data.

You can see that approach in the official RFC 8259 JSON standard, which defines the grammar used by interoperable JSON parsers. ECMA also describes JSON as its own data-interchange syntax, separate from full JavaScript behavior.

Why People Still Expect Comments To Work

The confusion comes from history and tooling. JSON grew out of JavaScript notation, and JavaScript itself allows comments. Many editors also color a .json file like code, which nudges people toward writing tiny notes beside values.

Then there’s the config-file problem. Humans edit settings files more comfortably when they can leave reminders like “don’t change this in production” or “port must match the proxy.” That makes comments feel natural even in places where the format rejects them.

What A Strict Parser Will Reject

Any of these will fail in standard JSON:

• Single-line comments with //
• Block comments with /* ... */
• Trailing notes after a value on the same line
• Comment-only lines placed between properties

A strict parser does not “skip past” those tokens. It stops because the file is no longer valid JSON text.

Does JSON Support Comments? In Practice Vs In Spec

This is where teams get tripped up. In the spec, the answer is no. In day-to-day work, you may still see comments inside files that look like JSON because some tools accept a non-standard extension.

That means two different questions are often being mixed together:

1. Is commented JSON valid according to the JSON standard?
2. Will this one editor, app, or build tool accept a commented file anyway?

The first answer stays no. The second answer depends on the tool.

JSONC And Similar Variants

Some tools use JSON-like formats that permit comments. A common one is JSONC, short for JSON with Comments. Its spec allows single-line and block comments and recommends using the .jsonc extension so people know the file is not plain JSON. The draft JSONC specification spells that out clearly.

This is why a file may work inside one editor and fail the moment you pass it to another parser, linter, API, or runtime. The file was never standard JSON in the first place. It was a JSON-like dialect accepted by that tool.

Pattern	Valid In Standard JSON?	What Usually Happens
{"name":"Rita"}	Yes	Works in strict parsers
// user name	No	Parser error before data is read
/* user name */	No	Parser error in strict tools
{"name":"Rita"} // note	No	Fails after the closing brace
{"port":3000,}	No	Trailing comma error in strict parsers
{"_comment":"dev only","port":3000}	Yes	Parses cleanly, though the note becomes data
settings.jsonc with // notes	No	May work only in tools that read JSONC
tsconfig.json with comments	Not standard JSON	Accepted by TypeScript tooling

Where You’ll See Commented JSON Anyway

Config files are the biggest source of mixed expectations. TypeScript’s own docs show commented examples inside tsconfig.json, which works because the TypeScript toolchain reads that file with its own rules rather than as raw, strict JSON. You can see that in the official tsconfig.json documentation.

VS Code settings files are another common case. They look like JSON, but many are treated as JSON with comments. That feels convenient when you stay inside that editor. It turns risky when the same file gets copied into a tool that expects strict JSON and nothing else.

APIs, package data, exported payloads, and machine-to-machine files should be treated much more strictly. Those are the places where commented JSON causes the most pain because another system may parse the payload with no tolerance at all.

Why This Matters For Teams

One developer may say, “It works on my machine,” because their editor strips comments or reads JSONC. Another developer may run a build step, a validator, or a deployment script that reads the file as standard JSON and gets a hard failure.

That turns a tiny note into a broken pipeline. The bug is not the comment text itself. The bug is the mismatch between a loose local tool and a strict parser later in the chain.

Safer Ways To Add Notes Without Breaking JSON

If humans need extra context, there are a few clean options.

Use A Real Comment-Friendly Format For Human-Edited Config

If the file is mainly for people to edit, use a format your tool actually expects, such as JSONC, YAML, or TOML. That choice should be made on purpose, with the file extension and parser matching the format from the start.

Keep Notes Outside The JSON File

This works well for API payloads, seed files, and data passed between services. Store the explanation in README text, schema docs, or inline developer docs near the file path. The data stays clean, and the notes stay readable.

Store Notes As Data Only When You Mean It

You can add fields like "_comment" or "description" inside the object. That keeps the JSON valid, though the note becomes part of the payload. This is fine when downstream code can ignore it or when the schema already allows metadata fields.

It is not a drop-in stand-in for real comments. If another service consumes every field, that note may get stored, indexed, or exposed.

Need	Better Choice	Trade-Off
Human-edited local config	JSONC or another comment-friendly format	Tied to tools that understand that format
API payloads and data exchange	Strict JSON with no comments	Notes must live elsewhere
Need inline explanation inside valid JSON	Metadata field like "_comment"	The note becomes real data
Shared team settings with validation	Strict JSON plus schema docs	Less handy during quick edits

Best Rule To Follow Before You Save A File

Ask one plain question: who will parse this file next?

If the answer is “an API, library, validator, or another system I don’t control,” stay with strict JSON. No comments. No trailing commas. No assumptions.

If the answer is “a tool that clearly documents JSONC or another relaxed parser,” comments may be accepted, but only inside that boundary. Don’t treat that as proof that JSON itself allows them.

A Simple Team Policy That Prevents Headaches

• Use .json only for strict JSON
• Use .jsonc when comments are allowed by the tool
• Document parser expectations in the repo
• Validate shared JSON files in CI with a strict parser

That small rule set clears up most comment-related bugs before they land in production.

So, does JSON support comments? Standard JSON does not. Some tools accept comment-friendly variants that look close to JSON, and that’s where the confusion starts. Once you separate “JSON the spec” from “JSON-like config files,” the rule gets much easier to follow.