Why JSON Doesn't Allow Comments — and the JSON5/JSONC Variants That Do (and Why They Break Standard Parsers)

JSON5 and JSONC let you add comments and trailing commas — and if you've ever tried to add a comment to a JSON configuration file, you know why this extension exists and why switching between JSON and JSON5 requires careful handling

The previous articles on this site covered JSON vs YAML vs other formats, schema validation, structured logging, and the JavaScript integer precision limit. This article addresses JSON variants and supersets — specifically JSON5, JSONC, and JSON with Comments (three different names for overlapping-but-distinct extensions), why they emerged, and the interoperability issues they create.

Why JSON is so strict: intentional minimalism

JSON was designed by Douglas Crockford as a lightweight data interchange format — the specification is intentionally simple. No comments, no trailing commas, no single-quoted strings, no hex literals, no undefined.

The reasoning for no comments: Crockford has explained that comments were excluded deliberately to prevent people from including parsing directives in JSON (analogous to XML's processing instructions). The simplicity and strictness of JSON is what makes it easy to implement parsers and ensures interoperability.

The practical problem: JSON became ubiquitous for configuration files — not just data interchange — and configuration files are things humans read, write, and maintain. Configuration benefits enormously from comments explaining why a value is set the way it is. A JSON-based configuration file with no comments creates maintenance overhead.

The three "JSON with comments" variants

JSON5 (jsonspec.org): a proper superset specification that adds:

• Single-line (//) and multi-line (/* */) comments
• Trailing commas in arrays and objects
• Single-quoted strings
• Unquoted object keys (if they're valid identifiers)
• Hexadecimal numbers (0xFF)
• Infinity, NaN, and +/- prefixed numbers
• Multi-line string literals

JSON5 has an npm package, language support, and is used by Babel (the JavaScript transpiler) for its configuration format.

JSONC (JSON with Comments): a more conservative extension — adds only single-line and multi-line comments and trailing commas. No other deviations from standard JSON. Used by Visual Studio Code for its configuration files (settings.json, tsconfig.json, launch.json).

"JSON with Comments" — informally, any JSON-like format that permits // and /* */ comments. Often what people mean when they say "JSONC" generically. TypeScript's tsconfig.json is technically this.

The interoperability problem: parsers aren't compatible

Standard JSON parsers reject JSON5 and JSONC content. JSON.parse() in JavaScript throws SyntaxError on a comment or trailing comma. Python's json.loads() does the same.

This matters most when: configuration files written as JSONC/JSON5 need to be read by standard JSON parsers in tooling or automation. A tsconfig.json file with comments can't be read by a generic JSON parser — it requires either a TypeScript-specific reader or a preprocessing step that strips comments.

Common failure patterns:

• Script reads tsconfig.json with standard JSON parser → SyntaxError
• API response expected as JSON contains JSON5-style single-quoted strings → SyntaxError
• Configuration management tool tries to validate JSON file that's actually JSONC → Validation fails incorrectly

The correct approach: always know which format you're actually working with, and use the matching parser. Don't assume "this looks like JSON" means it's parseable by a standard JSON parser.

YAML as an alternative that solved the comment problem differently

YAML supports comments natively (# begins a comment) and allows trailing commas (arrays end at the structural indent, not a comma). It became popular for configuration files partly for this reason.

YAML's tradeoffs compared to JSON:

• More human-readable and writeable for configuration
• Significantly more complex spec (YAML is famously complex, with many edge cases)
• Several YAML parsing security issues (YAML parsers historically allowed arbitrary code execution via language-specific type constructors)
• Less universal library support than JSON

JSON5/JSONC emerged partly as a "keep the JSON simplicity and tooling, just add comments" alternative to switching fully to YAML.

Tools that handle JSON variants gracefully

IDE support: VS Code understands JSONC natively in its configuration files and provides syntax highlighting, comment support, and validation that correctly handles the extension. json.parse with comment-stripping is included.

Preprocessing: several npm packages (json5, strip-json-comments, json-comment-stripper) can process JSONC/JSON5 content into standard JSON before passing to standard parsers — the comment-stripping approach is simpler and more compatible than full JSON5 parsing.

Configuration loaders: webpack, Babel, Jest, and similar tools typically ship with configuration loaders that understand their own format's extensions — avoiding the need for manual preprocessing.

How to use the JSON Formatter on sadiqbd.com

1. For standard JSON: the formatter validates, pretty-prints, and minifies standard JSON — if your JSON is actually JSONC (has comments), it will fail validation; this is useful for discovering that a "JSON file" is actually a JSON variant
2. Before pasting JSON from configuration files: be aware that VS Code config files (settings.json, tsconfig.json) contain comments and trailing commas; strip these before pasting into standard JSON tools
3. For debugging JSON parse errors: if a standard JSON parser rejects your content, the formatter can help identify whether the error is a genuine JSON error or a JSON5/JSONC feature that was accidentally included

Frequently Asked Questions

Should I use JSONC or YAML for my application's configuration files? Both are defensible choices — the practical decision often comes down to existing tooling. If your stack already uses YAML (common in DevOps, Kubernetes, Docker Compose, CI/CD configs), staying in YAML maintains consistency. If your stack is JavaScript/Node.js heavy (where JSON is native), JSONC or JSON5 adds comments while staying close to JSON's familiar tooling. JSONC has the advantage of being parseable after comment-stripping, making it easier to process programmatically. YAML has the advantage of broader multi-language support and being the dominant format for infrastructure-as-code. For new projects without existing tooling constraints, YAML is marginally more standardized; for JavaScript-heavy projects, JSON5/JSONC is arguably more natural.

Is the JSON Formatter free? Yes — completely free, no sign-up required.

Try the JSON Formatter free at sadiqbd.com — validate, pretty-print, and minify JSON instantly.