Are JSON Comments Allowed? RFC 8259 Says No, But Here Are 4 Fixes

Does JSON support comments? — the short answer

No. RFC 8259 does not permit // or /* ... */ comments anywhere in a JSON document. The ban is structural: Section 2's grammar excludes them, so a strict parser must reject any comment with an "Unexpected token" error. Section 9, however, states that a parser "MAY accept non-JSON forms or extensions" — that single sentence is why JSONC and JSON5 can exist as legal alternatives.

If you need comments in your JSON, you have four practical options:

• JSONC — JSON with Comments, used by VS Code
• JSON5 — a well-specified superset of JSON that also adds comments, trailing commas, and more
• A workaround field such as "_comment": "..." that lives inside the JSON itself
• Strip the comments before feeding the file to a strict parser

This article walks through each option, explains when to pick which, and shows how to convert a JSON-with-comments file into clean JSON you can use everywhere.

Quick decision:

• If you are editing a VS Code or Microsoft config file: use JSONC
• If you are picking a config format for a new project: use JSON5
• If the parser is strict and you cannot change it: use a _comment field or strip the comments

Once you strip the comments, you can format and verify the result in FormatArc's JSON Formatter — everything runs in the browser, and nothing leaves your machine. For tips on producing clean, reviewable JSON output, see JSON Formatting Tips.

What RFC 8259 actually says about comments

RFC 8259 (Internet Standard 90, December 2017) does not contain the word "comment" anywhere. Comments are excluded structurally, not by an explicit prohibition.

The grammar (Section 2)

The whole JSON grammar fits in a few ABNF lines. The only insignificant characters between tokens are four whitespace bytes:

ws = *(
        %x20 /              ; Space
        %x09 /              ; Horizontal tab
        %x0A /              ; Line feed
        %x0D )              ; Carriage return

// and /* */ are not in the grammar, so a strict parser must reject them as an "Unexpected token" error. That is the formal reason every standards-conforming JSON parser refuses comments — there is simply no production rule that accepts them.

What parsers MAY do (Section 9)

The same RFC explicitly allows extensions:

A JSON parser MUST accept all texts that conform to the JSON grammar. A JSON parser MAY accept non-JSON forms or extensions.

This single sentence is why JSONC and JSON5 can exist without violating the standard. They are "extensions" the RFC explicitly permits, as long as data sent over the wire still conforms to the strict grammar so any other parser can read it.

The same rule across spec revisions

JSON's IETF specification has gone through three revisions — RFC 4627 (2006), RFC 7159 (2014), and RFC 8259 (2017) — and none of them have ever included comments in the grammar. ECMA-404, the parallel ECMA standard, takes the same position. Comments have been out of JSON since the format was first written down.

Why the JSON spec does not allow comments

Douglas Crockford, the original designer of JSON, removed comments on purpose. In his own words, people were using comments to embed parsing directives, which broke interoperability. The spec was simplified so that any two JSON parsers would behave identically.

The result is that JSON is:

• Small — the grammar fits on one page
• Unambiguous — every value has exactly one interpretation
• Portable — every language has a built-in parser that behaves the same

The cost is obvious: you cannot annotate a JSON file to explain why a setting exists. That is the tradeoff, and it is also the reason so many tools reach for a superset like JSONC or JSON5.

For the underlying syntax rules, see JSON Syntax Guide.

Option 1: JSONC — JSON with Comments

JSONC is an informal extension invented at Microsoft and used throughout VS Code. It adds two things on top of JSON:

• // single-line comments
• /* multi-line comments */

Everything else is the same as JSON. A JSONC file typically looks like this:

{
  // Which theme VS Code should use at startup
  "workbench.colorTheme": "Default Dark Modern",

  /* Editor settings
     applied to every language */
  "editor.tabSize": 2,
  "editor.formatOnSave": true
}

VS Code's settings.json, tsconfig.json, launch.json, and many Microsoft tools expect JSONC. You will also see it in Deno configs (deno.json) and other developer tooling.

How to parse JSONC

JSONC is not supported by built-in JSON.parse — you need a helper.

Node.js:

// npm install jsonc-parser
import { parse } from "jsonc-parser";
const data = parse(sourceText);

Python:

# pip install jstyleson
import jstyleson
data = jstyleson.loads(source_text)

VS Code itself ships with its own JSONC parser — that is why you can write comments inside settings.json without breaking anything.

Option 2: JSON5 — a cleaner specification

JSON5 (json5.org) is a formally specified superset of JSON that adds several ECMAScript 5 conveniences:

• Single-line and multi-line comments
• Trailing commas in objects and arrays
• Unquoted keys (when they are valid identifiers)
• Single quotes for strings
• Multi-line strings with line continuations
• Hexadecimal numbers, leading and trailing decimal points, and explicit Infinity and NaN

A JSON5 file can look remarkably relaxed:

{
  // Feature flags for the staging environment
  features: {
    newDashboard: true,
    legacyNotifications: false,
    rateLimitRps: 0xff,
  },
  welcomeMessage: 'Hello, world',
  /* trailing commas are fine */
}

Because JSON5 has an actual specification, libraries for it exist in almost every language: json5 for Node.js, pyjson5 for Python, json5 for Ruby, and so on.

JSONC vs JSON5: which should you use?

They look similar but have different trade-offs.

A simple rule of thumb:

• If you are editing a Microsoft or VS Code configuration file, you are already using JSONC — keep doing that
• If you are choosing a config format for a new project and want a spec you can point tools at, pick JSON5
• If interoperability with strict JSON parsers is critical, stay on pure JSON and use the workaround field pattern below

Workarounds for strict JSON

If you cannot change the parser — for example, because a third-party service expects plain JSON — you can still leave notes inside the file using ordinary string fields.

Pattern 1: the _comment field

{
  "_comment": "Increase retries before the upstream timeout kicks in",
  "retries": 3,
  "timeout_ms": 5000
}

Underscore-prefixed keys are conventionally ignored by consumers, and most code treats them as ordinary data. This is the simplest workaround.

Pattern 2: sibling keys for per-field comments

{
  "retries": 3,
  "retries_comment": "Any higher and we exceed the upstream timeout",
  "timeout_ms": 5000,
  "timeout_ms_comment": "Matches the load balancer timeout"
}

More verbose but makes it clear which comment belongs to which field.

Pattern 3: outer metadata block

{
  "$meta": {
    "generated_by": "deploy.sh",
    "purpose": "Service configuration for the staging environment"
  },
  "service": {
    "port": 8080,
    "retries": 3
  }
}

A top-level metadata object keeps the payload clean while preserving context.

These workarounds add real data to the file, which means strict parsers still accept them. The downside is that the extra fields become part of the schema and must be documented as such.

Strip comments before using a strict parser

If you have a JSONC or JSON5 file and need to feed it to a strict JSON parser, you have two choices: parse it with a JSONC/JSON5 library and re-serialize as JSON, or strip the comments with a regex.

Quick Node.js example using the json5 package:

// npm install json5
import JSON5 from "json5";
import fs from "node:fs";

const source = fs.readFileSync("config.json5", "utf8");
const data = JSON5.parse(source);
fs.writeFileSync("config.json", JSON.stringify(data, null, 2));

Or a minimal regex approach — fine for files you control, but fragile if strings can contain //:

const stripped = source
  .replace(/\/\/[^\n\r]*/g, "")
  .replace(/\/\*[\s\S]*?\*\//g, "");
const data = JSON.parse(stripped);

The safer path is always to use a real parser. Once the comments are gone, see JSON Formatting Tips for handling complex structures and spotting any remaining syntax errors.

Format the result with FormatArc

Once you have plain JSON, paste it into FormatArc's JSON Formatter to pretty-print the output and spot any remaining issues. If the parser is still complaining — typically with an "Unexpected token /" error — that error almost always means a comment is still in the file. See How to Fix JSON Parse Errors for the full list of causes.

FormatArc itself uses the built-in JSON.parse, so it will reject JSONC and JSON5 directly. The workflow is:

1. Strip comments (or parse with a JSONC/JSON5 library, then stringify)
2. Paste the result into the JSON Formatter
3. Read, verify, or copy the clean JSON

Everything runs in the browser — nothing leaves your machine.

Frequently asked questions

Are JSON comments permitted in RFC 8259?

No. JSON comments are not permitted by RFC 8259. The specification's grammar in Section 2 has no production rule for // or /* */, so any conforming parser must reject them as "Unexpected token". The standards-compatible alternatives are JSONC, JSON5, or stripping comments before parsing.

Does RFC 8259 explicitly say JSON comments are not allowed?

Not in those words — RFC 8259 never uses the term "comment". The prohibition is implicit. Section 2 defines the entire JSON grammar in ABNF and lists only four insignificant characters between tokens (space, tab, line feed, carriage return). Because // and /* */ are absent from the grammar, a conforming parser must reject them. Section 9 then permits parsers to accept "non-JSON forms or extensions", which is the legal basis for JSONC and JSON5.

Where does RFC 8259 say JSON comments are not allowed?

RFC 8259 never uses the word "comment". The ban is structural: Section 2 defines the entire JSON grammar in ABNF, and the only insignificant characters between tokens are space, tab, line feed, and carriage return (ws = *( %x20 / %x09 / %x0A / %x0D )). There is no production rule for // or /* */, so a conforming parser must reject them as "Unexpected token". Section 9 then allows parsers to accept "non-JSON forms or extensions" — which is the legal basis for JSONC and JSON5.

Why do VS Code settings.json and tsconfig.json allow comments?

Both files are technically invalid JSON under RFC 8259, but VS Code and the TypeScript compiler ship their own JSONC parsers and treat the files as JSONC rather than strict JSON. This is exactly the "non-JSON forms or extensions" case Section 9 permits. The trade-off is portability: other tools that use JSON.parse directly will fail on the same file with an "Unexpected token /" error unless they also understand JSONC.

Can I use // or /* comments in a regular .json file?

Not if the file is going to be read by a strict parser such as JSON.parse, json.loads, or encoding/json. The parser will reject the file with an "Unexpected token" error on the first comment. Rename the file to .jsonc and use a JSONC-aware loader, or switch to JSON5.

Why does VS Code let me write comments in settings.json?

VS Code treats settings.json and similar files as JSONC, not strict JSON. Its built-in parser accepts // and /* */ comments. Other editors that use JSON.parse to read the same file will fail unless they also understand JSONC.

Is JSON5 a standard?

JSON5 has a published specification at spec.json5.org, but it is not an IETF or ECMA standard. It is widely supported in developer tooling but is not a replacement for RFC 8259 JSON in APIs or on the wire.

Should I use _comment or switch to JSON5 for my config file?

If the file is read by many different tools — some of which only understand strict JSON — stay on plain JSON and use the _comment pattern. If the file is consumed only by code you control, JSON5 gives you real comments and is less noisy.

Does FormatArc support JSONC or JSON5?

FormatArc's tools use the browser's built-in JSON.parse, which is strict. You will need to remove comments or parse through a JSONC/JSON5 library first, then paste the result into FormatArc's JSON Formatter.

What about YAML?

YAML supports comments natively with #. If you mostly need the comments and can change the format, YAML is often the better choice for configuration files. See YAML vs JSON: Key Differences for the full comparison, or jump straight to the YAML Syntax Guide.

Related reading

If you want to understand JSON itself better:

• What is JSON? — the basics of the format
• JSON Syntax Guide — the rules strict JSON follows

If you chose JSONC or JSON5 and need to work with the output:

• JSON Formatting Tips — clean output once the comments are gone
• How to Fix JSON Parse Errors — when your comments slip past you

If you need comments and can switch formats:

• YAML vs JSON: Key Differences — the config-friendly alternative
• YAML Syntax Guide — learn YAML if you need comments and more

Summary

• Standard JSON does not support comments — that is by design
• JSONC adds // and /* */ comments and is used by VS Code
• JSON5 is a formal superset with comments, trailing commas, and looser syntax
• If you cannot change the parser, add an _comment field or an outer metadata block
• After stripping comments, pretty-print the result in FormatArc's JSON Formatter