JSON Comments Are Not Allowed: Why and What to Use Instead

Douglas Crockford, who created and standardized JSON, deliberately removed comment support in 2012. In a post on Google+, he explained his reasoning: he had observed that people were using comments to embed parsing directives in configuration files, similar to how XML processing instructions work. These directives told specific parsers to change their behavior based on comment content. Crockford realized that allowing comments would destroy interoperability, because different parsers would start reading comments differently and JSON would fragment into incompatible dialects.

The resulting specification, now codified in RFC 8259 published in 2017, defines JSON with no comment syntax at all. Section 2 of the RFC defines a JSON text as a serialized value and provides a formal grammar in which no comment production exists. The grammar covers only values, objects, arrays, strings, numbers, and the three literal names true, false, and null. A forward slash character has no special meaning in JSON grammar and appears only within strings. Encountering a slash outside of a string is therefore a syntax error.

This decision is frequently criticized by developers who want to annotate configuration files with explanations of what each setting does. The criticism is reasonable because JSON is widely used as a configuration format despite being designed primarily as a data interchange format. Configuration files benefit from comments because they document intent, warn about side effects, and explain non-obvious values. Data interchange payloads generally do not need comments because the sender and receiver share a protocol specification.

The tension between JSON's intended use as a data format and its actual widespread use as a configuration format has produced several workarounds, each with different tradeoffs. Understanding why comments are excluded from the specification helps you choose the right workaround for your situation rather than working around a mistake, because comments were not accidentally omitted from JSON.

When JSON.parse throws a SyntaxError mentioning an unexpected token that is a slash, hash, or hyphen, the immediate diagnosis is that the file contains comments or comment-like syntax. A forward slash at the start of a comment shows up as 'Unexpected token /' in the error message. Hash symbols, which appear in TOML and Python configuration files, produce 'Unexpected token #'. An opening angle bracket from YAML document separators produces 'Unexpected token <'.

The error message includes a position number, which identifies the character offset in the string where the parser failed. To find the comment, count characters from the start of the file to that position, or divide the position by the approximate line length to estimate which line contains the problem. Modern editors with JSON syntax highlighting will underline the comment in a way that reveals the problem immediately, which is why editing a JSON file in a JSON-aware editor rather than a plain text editor catches these issues before running the code.

For configuration files loaded by build tools, the error may not appear directly as a SyntaxError from JSON.parse. The tool may wrap the error in its own message format. Webpack, for example, produces a detailed configuration error that may obscure the underlying parse failure. Looking for the words 'Unexpected token' anywhere in the error output usually reveals the root cause. Running node -e "JSON.parse(require('fs').readFileSync('file.json', 'utf8'))" from the command line is a quick way to directly test whether any JSON file is parseable by the native parser.

If you inherit a large codebase and need to find all JSON files that contain comments, a recursive grep for the pattern // or /* within .json files will identify candidates. The command grep -r '//' --include='*.json' will produce false positives for URLs in string values, so manual inspection of the results is necessary. A more precise approach is to run a linter such as ajv or jsonlint against each file, which reports syntax errors without false positives from URL strings.

The strip-json-comments npm package, maintained by Sindre Sorhus, is the most straightforward solution when you want to keep writing JSON with comments in config files but need to load them with standard JSON.parse. The package accepts a string containing JSON with comments and returns a string with the comments replaced by spaces. Replacing comments with spaces rather than removing them entirely preserves the character positions of all remaining tokens, which means that if JSON.parse subsequently throws a syntax error, the error position in the stripped string maps correctly to the corresponding position in the original file.

The package supports both single-line comments starting with // and multi-line block comments delimited by /* and */. It also handles the case where a URL inside a string contains // — the package is smart enough not to treat a forward slash inside a quoted string as the start of a comment. This makes it safe to use with JSON files that contain URLs as string values.

Usage in a configuration loading function is simple: import the package, call stripJsonComments on the raw file content, then pass the result to JSON.parse. This two-step process can be abstracted into a loadJson function that replaces all direct JSON.parse calls on file content throughout the codebase. Using a centralized loading function also makes it easy to add other preprocessing steps later, such as environment variable substitution or schema validation.

For projects where every developer contributes to configuration files, adding a note to the project README or a comment in the loader code that explains the strip-json-comments preprocessing step prevents confusion when someone tries to parse the same file directly and encounters a syntax error. The .json file extension is slightly misleading in this case because the file is technically JSONC or JSON-with-comments rather than standard JSON. Some teams prefer to rename such files to .jsonc to make the format explicit.

JSON5 and JSONC are both supersets of JSON that add comment support, but they differ significantly in scope and intended use. JSON5, defined at json5.org, adds a substantial set of new features beyond comments: unquoted object keys that follow JavaScript identifier rules, single-quoted strings, trailing commas after the last item in objects and arrays, hexadecimal numbers, and support for positive and negative infinity and NaN as number values. JSON5 is essentially a subset of ECMAScript 5 that adds a serialization format closer to JavaScript object literal syntax.

JSONC, which stands for JSON with Comments, is a more conservative extension. It adds only single-line and multi-line comment support to standard JSON and makes no other changes to the grammar. The JSONC format is used by VS Code for its configuration files, including .vscode/settings.json, .vscode/launch.json, and .vscode/extensions.json. VS Code recognizes the .jsonc extension and enables JSONC language mode automatically. However, JSONC is not formally standardized as a distinct specification in the way JSON5 is, and different implementations may accept slightly different supersets.

The choice between JSON5 and JSONC depends on what your config file needs. If you only need comments and your tool chain can handle them, JSONC with strip-json-comments is simpler because you stay closer to standard JSON. If you also need trailing commas for easier editing, unquoted keys for brevity, or other JSON5 features, then adopting JSON5 with the json5 package gives you a richer format. However, JSON5 requires that all consumers of the file use a JSON5-aware parser, and standard JSON tooling such as JSON.parse, jq, and most API clients cannot parse JSON5 directly.

A practical consideration is tooling support. JSON5 files can be used as Webpack config if you configure the appropriate loader. TypeScript's tsconfig.json actually accepts comments and trailing commas without requiring the .jsonc extension or the JSON5 package, because the TypeScript compiler uses its own JSON reader that accepts these extras. This means tsconfig.json files look like JSONC but are technically parsed by TypeScript's custom parser, not a general JSONC library.

VS Code's settings.json and TypeScript's tsconfig.json are among the most widely edited JSON-like files in web development, and both accept comments and trailing commas. This creates a misleading expectation that other JSON files should also accept comments, because developers learn their habits from these files.

TypeScript's compiler uses a custom JSON parser that intentionally accepts comments and trailing commas beyond the standard JSON grammar. This is a deliberate design choice to make tsconfig.json files more human-friendly. The TypeScript team did not publish a separate JSONC specification; they simply extended their parser. Other tools that read tsconfig.json, such as ts-node and ts-jest, use the TypeScript API to read the file and therefore also accept comments. A tool that reads tsconfig.json with Node's require() or JSON.parse, however, will fail on comments.

VS Code takes a similar approach. It maintains a fork of the JSON grammar that supports JSONC, and it applies this grammar to all files in the .vscode directory as well as files with the .jsonc extension. VS Code's built-in JSON language server handles validation, completion, and hover documentation for both standard JSON and JSONC files. The distinction is visible in the status bar at the bottom of the editor, which shows either JSON or JSON with Comments as the file type.

The practical lesson is that if a specific tool accepts comments in a JSON file, it is because that tool uses a custom parser, not because JSON itself allows comments. When you write scripts that process tsconfig.json or VS Code configuration files, use the appropriate reading strategy for that specific tool rather than assuming that accepted comments make the file valid standard JSON. For tsconfig.json in particular, use the TypeScript API's readConfigFile function or parseJsonConfigFileContent rather than JSON.parse to correctly handle all the edge cases the TypeScript compiler supports.

If your configuration file fundamentally requires comments for documentation, inline explanations, or team communication, using a format designed for configuration files rather than forcing comments into JSON is the better long-term approach. TOML and YAML both support comments natively and have mature parsers in every major programming language.

TOML, which stands for Tom's Obvious Minimal Language, uses the hash symbol as a comment delimiter. A hash character and everything following it on the same line is a comment. TOML has a simple, ini-like syntax for flat key-value pairs and uses square brackets for table headers that represent nested objects. It is explicitly designed for configuration files and prioritizes readability and ease of manual editing. Rust's package manager Cargo uses TOML for Cargo.toml, and many modern tools in the Rust ecosystem follow this convention. Node.js projects can read TOML using the @ltd/j-toml or toml packages.

YAML supports both hash-prefixed line comments and is more expressive than TOML for deeply nested configuration structures. YAML is the format of choice for Kubernetes manifests, GitHub Actions workflows, Docker Compose files, and Ansible playbooks. The indentation-based structure makes YAML config files easy to read when well-formatted, though the significant whitespace is a source of bugs when indentation is inconsistent. For a configuration file that already needs to describe complex nested structures, YAML avoids the need for the excessive quoting that JSON requires.

The practical migration path from JSON config files to TOML or YAML depends on your toolchain. If your Node.js application already reads a JSON config file with JSON.parse, switching to TOML or YAML requires adding a parser dependency and updating the loading code. This is a small one-time cost that pays for itself in readability, especially for configuration files that multiple developers edit regularly. Using the yaml package for YAML or @ltd/j-toml for TOML, the loading function is nearly identical to the JSON version except for the parsing step. The resulting configuration files can be extensively commented without any preprocessing step.