Choosing Comment Support for JSON Configuration Files: Strict JSON, JSONC, or YAML

Decision and constraints

You need to decide whether configuration files that are currently JSON should allow human‑readable comments. The decision must satisfy three constraints:

1. Compatibility with existing JSON parsers used by your services and tooling.
2. Preserving readability for developers who edit the files.
3. Ensuring that editors, linters, and CI pipelines continue to work without extra steps.

Comparison of options

Option	Comment support	Parser compatibility	Readability	Typical tooling
Strict JSON (RFC 8259)	None	Full – any standard JSON.parse works	Low – no inline notes	Universal (all languages, editors, CI)
JSONC (// line, /* block */)	Yes	Requires a tolerant parser or a pre‑strip step	High – comments can sit beside keys/values	VS Code, npm, Prettier, jsonc‑parser library
YAML	Yes (via #)	Full YAML parsers (e.g., js-yaml, PyYAML)	Very high – rich syntax, multi‑line strings	Many config tools (Ansible, Docker Compose), but stricter on tabs vs spaces

Trade‑offs

• Strict JSON guarantees interoperability but forces you to keep documentation outside the file (e.g., separate README).
• JSONC improves maintainability with inline comments, yet adds a small processing step: either configure your loader to use a JSONC‑aware parser or strip comments before feeding the text to a standard JSON parser. This step must be applied uniformly across all services that consume the config.
• YAML offers the richest commenting and structure, but introduces syntax sensitivity (tabs are invalid, spaces matter) and can be overkill for simple key‑value stores. Teams already using YAML elsewhere may benefit; otherwise the learning curve may outweigh the gain.

Concrete implementation (Node.js)

If you choose JSONC, you can avoid a custom comment‑stripping regex by using the jsonc-parser library, which respects string boundaries and handles both line and block comments.

1. Install the library in your project:

# Run in your project directory (requires npm or yarn)
npm install jsonc-parser

2. Create a configuration file with comments, e.g., config.jsonc:

{
  // Database connection settings
  "host": "db.example.com",
  "port": 5432,
  /* Enable verbose logging during development */
  "logLevel": "debug"
}

3. Load the file in your application (Node.js ≥ 12):

const fs = require('fs');
const { parse } = require('jsonc-parser');

function loadConfig(path) {
  const raw = fs.readFileSync(path, 'utf8');
  // parse throws if the syntax is invalid (including stray comment markers inside strings)
  return parse(raw);
}

const config = loadConfig('./config.jsonc');
console.log(config);
// Output: { host: 'db.example.com', port: 5432, logLevel: 'debug' }

Limitations and verification

The jsonc-parser approach adds a runtime dependency and a slight overhead compared to native JSON.parse. To verify that the loader works correctly:

• Unit test: Feed the loader a variety of inputs – comments at start, middle, end, nested block comments, and comment‑like sequences inside strings (e.g., "http://example.com/path#fragment") – and assert that the returned object matches the expected data and that no syntax error is thrown.
• Integration test: Replace your existing JSON config loader with the function above, start the full application with a config file containing comments, and compare key runtime metrics (e.g., database connection success, log level) against a baseline run using a strict‑JSON config. Functional equivalence indicates the comment handling does not alter behavior.

If you later decide to revert to strict JSON, simply remove the comments and change the loader back to JSON.parse; no data migration is required because the parsed object shape stays the same.