JSONC: JSON's Practical Cousin

  • The problem: Douglas Crockford intentionally excluded comments from JSON to prevent abuse
  • The reality: Config files desperately need comments—JSONC fills that gap
  • Not standard: JSONC isn't official JSON—most parsers will reject it

Files That Use JSONC

  • tsconfig.json: TypeScript config—despite the .json extension, it's actually JSONC!
  • settings.json: VS Code user and workspace settings
  • launch.json: VS Code debug configurations
  • tasks.json: VS Code task runner definitions
  • devcontainer.json: VS Code Dev Containers configuration
  • .vscode/*.json: Almost all VS Code config files support comments
  • azure-pipelines.yml: Uses JSON sections that allow comments

Comment Syntax

  • // single line: Most common, works anywhere
  • /* block */: Multi-line comments, can span lines
  • Trailing commas: JSONC often allows them too: [1, 2, 3,] ← valid!
  • Inside strings: // in a string value is NOT a comment—it's literal text

Why Crockford Banned Comments

  • His actual words: 'I removed comments because people were using them to hold parsing directives'
  • Example abuse: /* @directive: dont-validate */ before invalid data
  • JSON was designed for data interchange, not human-edited config files
  • Irony: Every major editor now supports JSONC for their own config files

JSONC vs JSON5 vs YAML

  • JSONC: JSON + comments + trailing commas. Nothing else changes
  • JSON5: JSONC + unquoted keys + single quotes + hex numbers + more
  • YAML: Completely different syntax, indentation-based, very flexible
  • TOML: INI-style sections, popular for Rust (Cargo.toml) and Python (pyproject.toml)

Parsing JSONC in Code

  • VS Code: jsonc-parser npm package (official, battle-tested)
  • Strip comments: npm install strip-json-comments, then JSON.parse()
  • TypeScript: Built-in ts.parseConfigFileTextToJson() handles tsconfig.json
  • Python: commentjson or json5 packages
  • Go: hujson package from Tailscale

Common Mistakes

  • Sending JSONC to an API: Standard JSON.parse() will throw—strip comments first!
  • Forgetting file extension: .jsonc tells editors to enable comment highlighting
  • Comments in arrays: // works, but some parsers struggle with inline comments
  • Nested block comments: /* /* nested */ */ doesn't work—block comments don't nest

Pro Tips

  • VS Code intellisense: Add '$schema' to get autocomplete for known config formats
  • Document deprecated options: // DEPRECATED: Use 'newOption' instead
  • Section headers: // ===== Editor Settings ===== for visual organization
  • Explain magic numbers: 'timeout': 30000 // 30 seconds in milliseconds
  • Link to docs: // See: https://docs.example.com/config for options