Can JSON Have Comments? JSON, JSONC, and JSON5

Why a commented file fails validation

JSON is a data format with a small grammar. A slash used to begin a line comment or block comment is not a valid token outside a string. JSON.parse and a strict JSON validator therefore reject comment syntax.

A file extension does not change the parser. Renaming a commented file to .json will not make it valid, and renaming an API payload to .jsonc will not make an API accept it. The program reading the file must explicitly support the chosen format.

// Not strict JSON
{
  "port": 3000 // local development port
}

// Valid JSON version
{
  "port": 3000
}

Choose JSONC for supported configuration files

JSONC adds comment syntax to JSON. It is useful in configuration workflows where the consuming application deliberately supports it. Do not assume every parser accepts trailing commas: check the application and parser options separately.

When a tool rejects a commented configuration, first determine whether it expects JSONC or strict JSON. You may be validating the file against the wrong format rather than finding an error in the application configuration itself.

Choose JSON5 only when the reader supports it

JSON5 offers a broader syntax, including comments and additional ways to write keys and strings. That can make a hand-edited configuration easier to maintain, but a strict JSON consumer cannot read it unchanged.

Use a compatible parser to read JSON5 and a serializer to produce ordinary JSON at the boundary. Treat conversion as a deliberate step, not a license to send JSON5 directly to a service that documents JSON request bodies.

Keep notes inside ordinary JSON

When a document must remain valid JSON, a note can be stored as a normal string field if the application permits that extra field. Such a field is data, not a comment, so it will be visible to downstream consumers.

For a schema-controlled payload, extra fields may be rejected. Keep explanatory text in accompanying documentation instead, or use a description field that the schema actually defines. Do not invent a _comment property in a production API request without checking the contract.

{"port":3000,"description":"Local development server"}

Remove comments without damaging strings

Do not remove everything following // with a regular expression. That can damage URLs such as "https://example.com" inside string values. A proper parser or a string-aware repair tool distinguishes comments from text.

For a one-off document, use the repair controls and inspect the result. Repair is a best-effort transformation and may change other non-JSON constructs too. For a repeatable build pipeline, use the format-specific parser and validate the generated JSON as a separate step.

• Confirm which format the receiving application supports.
• Keep an original copy of the commented document.
• Inspect string values after conversion, especially URLs and text containing slashes.
• Use schema validation when field names and types matter, not just syntax.