JSON with Comments

JSONC (JSON with Comments) extends standard JSON to allow JavaScript-style comments. Many development tools use JSONC for configuration files where comments help document settings. This parser strips comments to produce valid JSON while preserving the data structure.

Specifications

• jsonc-parser (VS Code)
• TypeScript tsconfig.json

Common Use Cases

• Parse tsconfig.json and jsconfig.json for TypeScript/JavaScript projects
• Read VS Code settings.json and extensions configuration
• Process Cloudflare wrangler.jsonc configuration files
• Edit ESLint, Prettier, and other tool configurations with inline documentation

Features

• Parse single-line comments (// comment)
• Parse multi-line comments (/* comment */)
• Handle trailing commas (common in JSONC files)
• Strip comments to produce valid JSON output
• All standard JSON Parser features (tree view, conversion)

Examples

{
  // Compiler options for the project
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    /* Enable all strict type checking options */
    "strict": true
  }
}

Tips

• VS Code, TypeScript, and many modern tools support JSONC natively.
• When sharing configuration, consider if recipients' tools support comments.
• Convert to standard JSON by stripping comments when tools require strict JSON.

Understanding JSON with Comments

JSONC (JSON with Comments) is an extension of standard JSON that allows JavaScript-style single-line (//) and multi-line (/* */) comments, as well as trailing commas after the last element in arrays and objects. While not an official standard, JSONC has become the de facto format for developer-facing configuration files where inline documentation improves maintainability.

Microsoft popularized JSONC through Visual Studio Code, which uses it for settings.json, keybindings.json, launch.json, and extensions.json. TypeScript's tsconfig.json and JavaScript's jsconfig.json are JSONC files, as are many ESLint, Prettier, and Babel configuration files when using the .json extension. Cloudflare's wrangler.jsonc explicitly uses the .jsonc extension to signal comment support.

The key advantage of JSONC over plain JSON is documentation. Configuration files often contain settings whose purpose is not obvious from the key name alone. Comments allow developers to explain why a setting exists, what valid values are, and what the consequences of changes might be. Trailing commas reduce version control noise by allowing the last element to have the same format as all others, so adding a new item only shows one changed line in a diff rather than two.

Under the hood, JSONC parsers work by stripping comments and trailing commas before passing the result to a standard JSON parser. This means the data model is identical to JSON — comments are metadata for humans, not data for programs. When converting JSONC to JSON for tools that require strict JSON compliance, the comments are simply removed. Microsoft's node-jsonc-parser library, used in VS Code, is the reference implementation for JSONC parsing.

JSONC is not an official standard defined by any RFC or ECMA specification. It is a convention popularized by Microsoft through VS Code and TypeScript, with behavior well-defined by the jsonc-parser library that serves as the reference implementation. Other tools that support JSONC — ESLint, Prettier, and various editors — follow the same conventions for single-line comments, multi-line comments, and trailing commas. Common JSONC files include tsconfig.json and jsconfig.json (TypeScript/JavaScript), VS Code settings files (settings.json, launch.json, tasks.json, keybindings.json), wrangler.jsonc (Cloudflare Workers), devcontainer.json (VS Code Dev Containers), and various other tool configurations. Any JSON file primarily edited by developers that could benefit from comments likely supports JSONC.

JSONC should only be used for configuration files read by tools with explicit JSONC support. API responses, data storage, and inter-service communication should always use standard JSON, since most JSON parsers will reject comments as syntax errors. To process a JSONC config file programmatically with a standard JSON parser, strip the comments first using a JSONC-aware library.

JSONC is more conservative than JSON5, which is a more extensive superset of JSON. While JSONC adds only comments and trailing commas, JSON5 also allows single-quoted strings, unquoted object keys, hexadecimal numbers, leading and trailing decimal points, Infinity and NaN, and multi-line strings. JSONC has broader tool support in the developer ecosystem, whereas JSON5 is used in specific configuration files like Babel's babel.config.json5 but has narrower adoption overall.