JSON vs JSONC (JSON with Comments)

JSONC, or JSON with Comments, is an extension of the standard JSON format that permits single-line (//) and multi-line (/* */) comments within the document. It is not an official standard but has gained widespread adoption in developer tooling, most notably in Visual Studio Code's configuration files like settings.json and tsconfig.json.

Why JSONC exists:

The original JSON specification, defined by Douglas Crockford, intentionally excluded comments to keep the format simple and to prevent abuse such as parsing directives or metadata annotations. However, configuration files are primarily read and maintained by humans, and the inability to add explanatory notes, document default values, or temporarily disable settings creates real friction. JSONC addresses this gap by allowing comments in files that are meant for human consumption.

Key differences between JSON and JSONC:

Standard JSON forbids any content that is not part of the defined grammar. A compliant JSON parser will throw a syntax error if it encounters // or /* */. JSONC parsers, on the other hand, strip comments before parsing, effectively treating them as whitespace. JSONC also typically permits trailing commas, making it easier to reorder lines without worrying about comma placement.

Where JSONC is supported:

• tsconfig.json (TypeScript compiler configuration) — always parsed as JSONC
• VS Code settings.json, launch.json, extensions.json
• ESLint configuration (.eslintrc.json when using flat config comments)
• The jsonc-parser npm package used by Microsoft tools Standard JSON APIs such as JSON.parse() in JavaScript, json.loads() in Python, and most HTTP clients do not support JSONC.

Common mistakes developers make:

The biggest mistake is using JSONC syntax in files that will be parsed by a standard JSON parser. For example, adding comments to a package.json file will cause npm install to fail because npm uses a strict JSON parser. Another mistake is assuming all JSON tools and libraries support JSONC. If you are not certain the consumer supports comments, do not include them. Some developers also confuse JSONC with JSON5, which is a separate superset allowing additional syntax like unquoted keys and single-quoted strings.

Best practices:

Use JSONC only when the consuming tool explicitly supports it. For standard JSON files, add documentation in a separate README or use a "_comment" key convention. When writing libraries that read JSON config files, consider supporting JSONC parsing to improve developer experience, but document this clearly.