skip to content

Why can a JSON configuration file not carry an inline comment, unlike the other members of the text family?

level: middleimportance: nice to knowfreq 28%

answer

  1. a grammar decision, not a parser one
  2. no comment production exists
  3. the sibling formats both have one
  4. a convention member is real data
  5. conventions replace missing grammar

basics

~20 s

The JSON grammar defines no comment production, so any comment text is a parse error. XML and YAML both have one. Teams work around it with a convention key, a sidecar file, or a superset dialect stripped before parsing.

solid answer

~50 s

It is a grammar decision, not a limitation of any parser. `JSON`'s grammar has no production for a comment, so comment text is simply invalid input — the usual rationale given is that the format was kept deliberately minimal and that comments in earlier formats attracted parser-specific directives. `XML` has `<!-- -->` and `YAML` has `#`, so both can carry rationale next to a value. Teams facing a hand-edited `JSON` file take one of three routes: a **convention member** such as `"_comment"`, which is real data that every reader must ignore and that travels to every consumer; a **sidecar document** holding the explanations, which drifts from the file it explains; or a **superset dialect** with comments that a build step strips before a standard parser sees it, which means the file humans edit is not the format the parser guarantees.

code

json · 5 lines
json
{
  "retryLimit": 3,
  "_comment_retryLimit": "3 matches the partner's own retry budget; higher duplicates charges",
  "timeoutSeconds": 30
}

go deeper

for a junior

Recall that the grammar defines no comment, so comment text is a parse error rather than an unsupported extra. The other two members of the text family both allow comments.

for a middle

Explain that this is a grammar decision made for minimalism, and name the three workarounds — a convention member, a sidecar file, a stripped superset dialect — with the cost of each.

for a senior

Show where it actually hurts: a hand-edited configuration under review with no place to record rationale, and a convention member that leaks into the contract and may trip a strict validator.

for a principal

Generalise it. A deliberately small grammar exports its gaps to your conventions — comments and namespaces are the two famous ones — so decide which documents are human-authored and give those a dialect whose grammar already covers the need.

## The grammar, not the parser The first thing to get right is where the restriction lives. It is not that parsers refuse to implement comments — it is that the `JSON` grammar defines no comment production at all, so comment text is not a feature that was left out of an implementation, it is invalid input. The rationale usually given for the choice is minimalism: keeping the grammar as small as possible, and avoiding the pattern seen in earlier formats where comment syntax became a channel for tool-specific directives that changed how a document was interpreted. The other two members of the family made the opposite choice: - `XML` has a comment construct, and it is part of the document tree that a processor may expose. - `YAML` has a line comment, and using it is normal practice in hand-written configuration. ## Why it only matters for documents a person edits On a machine-to-machine payload the absence is irrelevant: nobody writes the document and nobody reads the rationale. The bite comes when a `JSON` file becomes **configuration** — something in a repository, changed under review, where the answer to "why is this limit 30?" needs to live next to the 30. That is the moment the missing production is felt, and it is felt by the reviewer rather than by the program. ## The three workarounds and what each costs | Workaround | How it works | What it costs | | --- | --- | --- | | Convention member | Add a member such as `"_comment"` beside the real value | It is real data: it travels to every consumer, appears in every response, and each reader must know to ignore it | | Sidecar document | Keep the explanations in a separate file next to the configuration | Nothing keeps the two in step, so the explanation drifts from the value it explains | | Superset dialect | Author in a dialect that permits comments and strip them in a build step | The file humans edit is no longer the format the parser guarantees, and the stripped output is what is actually deployed | None of the three is disgraceful; the point is that all three move a documentation problem into either the data, the repository layout, or the build. ## The same gap in extensibility Comments are one instance of a broader pattern: **where the plain data model has no mechanism, ecosystems substitute a convention that no parser enforces**. The clearest second instance is extension fields. 1. Markup solves it in the grammar: two independently defined vocabularies can be combined in one document using prefixed names, so a vendor's additions cannot collide with the base vocabulary. 2. The plain data model has no namespace concept, so ecosystems reserve a key prefix, or agree that all vendor additions nest under one member. 3. Because the convention is social, a collision is caught by a reviewer or by a validator someone runs, never by the decode step. The symmetry is worth stating out loud in an interview: comments and namespaces are both cases where a deliberately small grammar pushes a real requirement out of the format and into the organisation's conventions. ## What a good answer sounds like A candidate who says "you just can't do it" has given half an answer. The complete one names the grammar as the reason, names the constructs the sibling formats have, and then shows awareness that the workarounds have distinct costs — one puts documentation into the payload, one lets it drift, one changes what you are actually parsing. The strongest answers close by noting that the constraint is a feature for a **payload**, where a smaller grammar means fewer legal spellings and fewer surprises, and only a liability for a **hand-edited file**, which is a hint that the two roles want different members of the family.

  • What is wrong with using a "_comment" member to document a JSON configuration value?
    It is not a comment, it is data. Every consumer decodes it, it travels on every response if the document is ever served, a strict validator may reject it as an unexpected member, and nothing ties it to the value it describes, so the two drift independently. It is a workable convention, but it puts documentation into the contract.
  • Comments are one missing mechanism. What is the other well-known one, and how do ecosystems fill it?
    Namespaces. Markup lets two independently defined vocabularies coexist in one document through prefixed names, so a vendor extension cannot collide with the base vocabulary. The plain data model has no equivalent, so ecosystems reserve a key prefix or nest all extensions under one agreed member — a convention that a reviewer or validator enforces, never the parser.

saying these in an interview costs you the question

  • Says some parsers support comments so the format does
  • Treats a convention member as equivalent to a real comment
  • Believes a sidecar file stays in step automatically
  • Thinks the sibling text formats also lack comments
  • Assumes a stripped superset dialect is what gets deployed