JSON (JavaScript Object Notation) is a lightweight data‑interchange format that’s easy for humans to read and machines to parse. One thing it deliberately leaves out is a comment syntax. This guide explains why, then walks through the practical workarounds developers use when they need to annotate a configuration file, an API payload, or a fixture.
You’ll see four idiomatic options — sidecar documentation, reserved keys like _comment, a strip‑before‑parse step, and the JSON5 superset — and learn when each is appropriate.
JSON is a text format that is completely language‑independent but uses conventions familiar to programmers of the C‑family of languages, including C, C++, C#, Java, JavaScript, Perl, Python, and many others. These properties make JSON an ideal data‑interchange language for APIs, configuration files, and persistent storage.
The grammar fits on a single page — objects, arrays, strings, numbers, booleans, and null.
Compact text with low parsing overhead, perfect for REST APIs and embedded systems.
Every mainstream language ships a JSON parser, so the same payload travels safely across stacks.
Whitespace is optional but freely allowed, which makes pretty‑printed JSON easy to diff and review.
JSON is a data interchange format, not a document language. A valid document encodes exactly one value (usually an object or array) so any compliant parser on any stack can recover the same structure—with no hidden instructions in the syntax.
Douglas Crockford, who popularised JSON, removed comments from the spec after seeing teams abuse them to smuggle parsing directives between tools, which broke interoperability. The fix was to forbid comment tokens entirely. RFC 8259 still requires strict parsers to reject // and /* … */ inside .json files.
Carry data only—no prose or machine directives embedded in the grammar.
Early adopters used comments as a side channel between tools instead of encoding that information as data.
Strict JSON.parse throws SyntaxError. Editors may still accept JSONC or JSON5 for local config files.
If a .json file has comments and “just works” in the editor, you are using a JSON extension (for example JSONC in VS Code or JSON5). The same bytes will fail JSON.parse in the browser or in many CI pipelines unless you strip comments first.
Although JSON does not natively support comments, several patterns are widely used to attach explanatory information to JSON data. Pick the one that matches who reads the file and who parses it.
Keep your JSON pristine and describe its structure in a sibling README.md or schema file. This is the only option that works with any JSON consumer because the data file itself never changes.
Add a string‑valued field whose name signals “ignore me”. Conventional choices are _comment, $comment (used by JSON Schema), or //. Every parser accepts them as ordinary data, and consumers that don’t recognise the key simply leave it alone.
{
"_comment": "User profile returned by GET /api/users/42",
"name": "John Doe",
"age": 30,
"city": "New York"
}If you control the runtime, write the file with C‑style comments and run a preprocessor (for example the strip-json-comments npm package) before handing the text to JSON.parse. This is exactly the trick VS Code uses for its settings.json.
{
"name": "John Doe", // user's full name
"age": 30, // age in years
"city": "New York" // current city
}JSON5 is a superset of JSON that allows comments, trailing commas, unquoted keys, and single‑quoted strings. JSONC (JSON with Comments) is a smaller superset used inside the VS Code ecosystem. Both require a dedicated parser.
{
// unquoted keys, trailing commas, and comments are allowed
name: "John Doe",
age: 30,
city: "New York",
}JSON.parse; never expose JSON5 from a public API.A practical pattern for hand‑edited config: prefix any documentation key with an underscore so it sorts together and stays distinct from real fields.
{
"_comment1": "This section describes the authenticated user.",
"user": {
"name": "John Doe",
"age": 30
},
"_comment2": "Postal address used for shipping.",
"address": {
"city": "New York",
"zip": "10001"
}
}Consumers parse the document normally; readers see inline context next to the data it describes.
Strict JSON has no comment syntax — RFC 8259 forbids // and /* … */.
For portable annotations, use a reserved key such as _comment or $comment.
Use JSON5 or a strip‑before‑parse step only inside trusted tooling, never on public APIs.
SyntaxError. If a parser accepts comments it is reading a JSON extension such as JSONC or JSON5, not strict JSON._comment is a community convention. $comment is reserved by JSON Schema for non‑normative annotations and is therefore safer inside schema documents.JSON.parse on the response body and will fail on JSON5 features. Reserve JSON5 for files developers edit by hand, and emit strict JSON over the wire.JSON.parse on the result. VS Code uses the same technique to load settings.json.Now that your JSON is comment‑free, learn how JSON.parse() turns the text into a live JavaScript value — including reviver functions and error handling.
The original JSON specification did include // comments, but Douglas Crockford removed them after seeing teams abuse comments to embed parsing directives. Today RFC 8259 forbids comments entirely — any parser that accepts them is parsing a JSON extension, not JSON.
12 people found this page helpful