JSON Comments: Why JSON Has None and 5 Workarounds That Work

Why JSON has no comments

Douglas Crockford's reasoning, explained in a widely cited 2012 post, is rooted in interoperability. He observed developers using SGML and XML comment syntax as parser-specific processing directives — <!-- IE only --> comments that told certain parsers to behave differently from others. A document that one parser treated as pure data was interpreted as instructions by another. The result was version-specific and browser-specific parsing behavior that made consistent data interchange impossible. As Crockford put it: "I removed comments from JSON because I saw people using them to hold parsing directives in a way that would have destroyed interoperability."

By removing comments from JSON entirely, the specification guarantees that every conformant JSON parser produces identical output from the same input. There is no room for processor-specific directive comments, no parser flags, and no lenient modes. RFC 8259 (2017), the current JSON specification, does not mention comments anywhere. Any parser that accepts // or /* */ syntax is implementing a superset of JSON — useful for configuration files, but not strictly JSON. If you want to understand the full set of JSON syntax rules, the syntax guide covers every valid construct.

The consequence is unambiguous: json.loads() in Python and JSON.parse() in JavaScript both throw on any comment syntax, with no option to enable comment support in the standard library. This is a feature, not a limitation. For data interchange between systems, identical parsing behavior across all implementations is exactly what you want. For human-authored configuration files, however, the lack of comments is a genuine inconvenience — which is why multiple workarounds exist and are widely used.

What happens when you try to add comments

Both // single-line and /* */ block comments are invalid in any JSON document. There are no exceptions — no parser flags, no lenient modes in the standard library. Attempting to parse JSON with comments throws immediately:

// JavaScript
JSON.parse('{ "name": "Alice" // user }')
// SyntaxError: Unexpected token / in JSON at position 18

JSON.parse('{ /* config */ "debug": true }')
// SyntaxError: Unexpected token / in JSON at position 2

# Python
import json
json.loads('{ "name": "Alice" // user }')
# json.JSONDecodeError: Expecting ',' delimiter: line 1 column 20

The error position points to the first / character — the parser has no idea it is looking at a comment and simply reports an unexpected token. There is no way to make JSON.parse() or json.loads() accept comments without first removing them from the string. If you are trying to fix invalid JSON that accidentally contains comments, you must strip the comments before parsing. The workarounds below each approach this problem differently.

Workaround 1: JSONC (JSON with Comments)

JSONC is a superset of JSON that adds // single-line and /* */ block comment support. It is used by VS Code for its configuration files — .vscode/settings.json, tsconfig.json, jsconfig.json, launch.json, and tasks.json are all parsed as JSONC. Files outside of VS Code commonly use the .jsonc extension to signal that the file requires a JSONC-aware parser. Node.js does not parse JSONC natively.

The primary library is jsonc-parser (npm, maintained by Microsoft), which is the same parser VS Code uses internally:

import { parse } from 'jsonc-parser'

const text = `{
  // Database config
  "host": "localhost",
  "port": 5432, /* default PostgreSQL port */
  "debug": false
}`

const config = parse(text)
// { host: 'localhost', port: 5432, debug: false }

An example .jsonc file with both comment styles:

{
  // Database config
  "host": "localhost",
  "port": 5432, /* default PostgreSQL port */
  "debug": false
}

Important distinction: JSONC does NOT allow trailing commas — that is a JSON5 format feature. JSONC adds only comments, nothing else. Use JSONC when you need to add comments to VS Code configuration or TypeScript configuration files, or when you want a minimal extension to JSON without the broader changes that JSON5 introduces. You can also configure VS Code to treat any .json file as JSONC via "files.associations": { "*.config.json": "jsonc" } in your workspace settings.

Workaround 2: JSON5

JSON5 is a superset of JSON (published 2012) that adds a broader set of human-friendly features: // and /* */ comments, trailing commas in objects and arrays, single-quoted strings, unquoted identifier keys, hexadecimal numbers, and multi-line strings. Files use the .json5 extension. Parse with the json5 npm library:

import JSON5 from 'json5'

const config = JSON5.parse(`{
  // Server settings
  host: 'localhost',
  port: 3000, // trailing comma OK
  tags: [
    'production',
    'v2', // trailing comma in array
  ],
}`)
// { host: 'localhost', port: 3000, tags: ['production', 'v2'] }

Serialization works the other way with JSON5.stringify(obj, null, 2), which produces a JSON5 document with trailing commas and optionally unquoted keys. JSON5 is the right choice for hand-authored configuration files where readability matters most — the combination of comments, trailing commas (which survive copy-paste reordering without syntax errors), and unquoted keys makes the format noticeably more ergonomic than plain JSON.

Avoid using JSON5 for data interchange between systems — recipient systems must also support JSON5, and most HTTP APIs expect standard JSON. JSON5 is a config file format, not a wire format. For data interchange, JSONC is a safer option (smaller superset, easier to strip) or stick with standard JSON and use one of the other workarounds for comments.

Workaround 3: the "_comment" key

The "_comment" trick stores comments as legitimate JSON string values under a conventional key name. No library is needed — standard JSON parsers accept it because { "_comment": "some note", "value": 42 } is perfectly valid JSON. Some developers prefer "//" as the key name because it visually resembles a comment. The key-value pair appears in the parsed object and must be stripped by the consuming application, but for simple config files that you control end-to-end, this is often the most portable option:

{
  "_comment": "Database configuration for production",
  "host": "db.example.com",
  "port": 5432,
  "_comment_2": "Increase pool size under high load",
  "pool": 10
}

Drawbacks: the comment key appears in the parsed object (must be stripped by application code), only one comment per key name unless you use "_comment_1", "_comment_2" suffixes, and you cannot place a comment after a specific value inside an array — only at the object level. An alternative is to use an array: "_comments": ["note 1", "note 2"].

Best for: simple configuration files where you control the consumer and can ignore or filter _comment keys, and where adding a dependency for JSONC or JSON5 parsing is not worth it. This approach works in every language and every JSON parser with zero dependencies — it is the most portable workaround of the five.

Workaround 4: strip-json-comments

The strip-json-comments npm package (2M+ weekly downloads) strips // and /* */ comments from a JSON string before passing it to JSON.parse(). This lets you write .json files with comments while keeping the standard file extension and using the standard parser:

import stripJsonComments from 'strip-json-comments'
import { readFileSync } from 'fs'

const raw = readFileSync('config.json', 'utf8')
const config = JSON.parse(stripJsonComments(raw))

The package handles edge cases correctly — it won't strip // that appears inside a JSON string value (e.g., { "url": "https://example.com" }is handled safely). It also handles trailing commas if you pass { trailingCommas: true } as the second argument:

const config = JSON.parse(
  stripJsonComments(raw, { trailingCommas: true })
)

Use strip-json-comments when you want to keep the standard .json file extension with comment support in a Node.js app, without switching to JSONC or JSON5. It is also the right choice when you are reading config files that were written by humans (and may contain comments) but need to feed them into systems that expect standard JSON. Use Jsonic's JSON Formatter to clean up and re-indent your JSON after stripping comments during a migration.

Workaround 5: switch to TOML or YAML for config

If comments are important throughout your configuration — not just occasionally — the cleanest solution is to switch formats entirely. TOML (# comments) and YAML (# comments) both support comments natively and are widely adopted for configuration files.

TOML in Node.js: install @iarna/toml from npm, or use Node.js 22's built-in node:toml module (no install needed). YAML in Node.js: installjs-yaml and call yaml.parse(text).

# TOML example (config.toml)
# Server settings
[server]
host = "localhost"
port = 3000 # default port

[database]
# Increase pool under high load
pool = 10

# YAML example (config.yaml)
# Server settings
server:
  host: localhost
  port: 3000  # default port

database:
  # Increase pool under high load
  pool: 10

The trade-off comparison across all five options:

tsconfig.json and package.json — special cases

Two files cause frequent confusion because they share the .json extension but behave differently with respect to comments. tsconfig.json accepts comments even though it uses a .json extension — the TypeScript compiler uses a JSONC parser internally, not standard JSON.parse(). You can add // and /* */ comments anywhere in tsconfig.json without errors:

{
  // TypeScript compiler options
  "compilerOptions": {
    "strict": true, /* recommended for all projects */
    "target": "ES2022",
    "module": "ESNext"
  },
  "include": ["src"]
}

package.json, on the other hand, does NOT accept comments. npm uses strict JSON parsing and will reject a package.json with comments — npm install and other npm commands will fail with a parse error. This is a common mistake when developers assume all .json files behave the same way. The file extension alone does not determine which parser is used; it depends on which tool reads the file.

VS Code highlights JSON files differently based on its "JSON with Comments" language mode. You can configure VS Code to treat additional files as JSONC via .vscode/settings.json:

{
  "files.associations": {
    "*.config.json": "jsonc",
    ".eslintrc": "jsonc"
  }
}

This changes VS Code's syntax highlighting and validation for those files but does not change how Node.js or npm parses them — you still need a JSONC-aware parser in your code if the application reads these files at runtime.

Frequently asked questions

Why doesn't JSON support comments?

Douglas Crockford removed comment support from JSON when formalizing the specification, and explained the reason in a 2012 post. He had observed developers adding comments to data-interchange formats (like SGML) that their parsers would then use as processing directives — for example, <!-- IE6 fix --> comments that told specific parsers to behave differently. This practice broke interoperability: a document that one parser treated as data was interpreted as instructions by another. By removing comments entirely, Crockford ensured that every JSON parser produces identical output from the same input. There is no way to add parser-specific directives in JSON, which is precisely the point. RFC 8259, the current JSON standard, makes no mention of comments. Any parser that accepts comment syntax is implementing a superset of JSON, not JSON itself. JSON.parse() in every language's standard library is a strict parser that rejects comments.

How do I add comments to a JSON file?

You have 5 options depending on your use case: (1) JSONC — use the jsonc-parser library (npm) to parse .jsonc files that contain // and /* */ comments. Used by VS Code for its settings files. (2) JSON5 — use the json5 library (npm) for .json5 files with comments, trailing commas, and unquoted keys. (3) "_comment" key — add a key with a conventional name like "_comment" or "//" and put your comment as the string value. No library needed — just ignore the key when consuming the data. (4) strip-json-comments — use this npm package to strip comments before passing the string to JSON.parse(). Useful for keeping .json extension while adding comment support. (5) Switch to TOML or YAML — both support # comments natively and are better choices for config files where comments are important throughout the document.

Does tsconfig.json support comments?

Yes. tsconfig.json is parsed by the TypeScript compiler using a JSONC (JSON with Comments) parser, not standard JSON.parse(). This means you can add // and /* */ comments anywhere in tsconfig.json without errors. VS Code also uses a JSONC parser for its own config files (.vscode/settings.json, .vscode/launch.json). However, package.json uses strict JSON parsing by npm and does not accept comments — adding comments to package.json will break npm install and other npm commands. The file extension alone doesn't determine which parser is used; it depends on which tool reads the file.

What is JSONC?

JSONC stands for JSON with Comments. It is a superset of standard JSON that adds support for // single-line comments and /* */ block comments. JSONC files commonly use the .jsonc extension but may also use .json when the consuming tool is known to use a JSONC parser (such as VS Code configuration files). JSONC does not add any other JSON extensions — it does not allow trailing commas, unquoted keys, or other JSON5 format features. The jsonc-parser npm library (maintained by Microsoft) is the reference implementation for parsing JSONC in Node.js. VS Code uses JSONC for its settings files, which is why you can add comments to settings.json, keybindings.json, launch.json, and tasks.json without VS Code complaining. If you open those files in a non-JSONC-aware editor, the comments will appear as syntax errors.

What is the _comment trick in JSON?

The "_comment" (or "//") trick stores comments as legitimate JSON string values under a conventional key name. Since JSON allows any string key, { "_comment": "This is a note", "value": 42 } is perfectly valid JSON. Some developers prefer "//" as the key because it visually resembles a comment. The limitation: the key-value pair appears in the parsed object and must be filtered out by application code. Multiple comments require multiple keys ("_comment1", "_comment2") or you can use an array "_comments": ["note 1", "note 2"]. You cannot place a comment after an array element or after a specific value — only at the object level. This approach requires zero dependencies and works with any JSON parser, making it the most portable workaround for simple, infrequent comments in data files.

Can I use comments in JSON in Python?

Python's json standard library uses a strict parser and rejects all comment syntax: json.loads('{"a": 1 // comment}') raises json.JSONDecodeError. To use comments in Python-read JSON files, use one of: (1) json5 library (pip install json5) — supports comments, trailing commas, unquoted keys: import json5; json5.load(file). (2) jsoncomment library (pip install jsoncomment) — strips // and /* */ before parsing. (3) commentjson library — similar approach. (4) Manual strip with re.sub(r'//.*', '', raw) — this naive approach fails for // inside string values; the libraries handle this correctly. For production, use json5 or switch to TOML/YAML with tomllib (Python 3.11 standard library) or pyyaml.