JSON parsers that can accept comments

Original Article ↗ Hacker News Discussion ↗

Whether JSON should allow comments is reigniting long‑running tensions between strict standards and real‑world usage. Many developers value comments for human-edited configuration files and point to alternatives like JSON5, YAML, TOML, EDN, or HuJSON, while others argue that adding comments to JSON itself creates ambiguity, interoperability problems, and potential abuse (e.g., hidden pragmas in comments). The exchange highlights a broader question: when a minimal data-interchange format is widely repurposed for configuration and documentation, should the ecosystem adapt with new formats and tooling, or should the core spec remain rigid and rely on preprocessors and extensions instead.

Spec vs. “Real World” JSON

  • Many insist that “JSON has no comments” is fundamental: if a parser accepts comments, it’s not JSON anymore, just a new format.
  • Others argue the spec is mismatched with reality: JSON is widely used for human-edited config, where comments are strongly desired.
  • Several note this is exactly the “one more standard” problem: ad‑hoc “JSON+comments” breaks interoperability.

Arguments for Allowing Comments

  • Helpful for configuration and documentation: explain options, annotate tricky values, temporarily disable entries.
  • Comments can be treated like whitespace: ignored by parsers, not round-tripped, purely to aid readability.
  • Many tools already strip comments before standard parsing; nothing stops any app from doing the same today.
  • Some see no real protection in banning comments: people already stuff extra meaning into string fields or special keys.

Arguments Against Allowing Comments

  • Original spec removed comments because people abused them for pragmas and directives, making behavior parser‑dependent.
  • Once comments exist, people will attach semantics to them (transform hints, type/format metadata), creating subtle incompatibilities.
  • Round-tripping becomes complex: preserving comment locations and associations would require expanding the data model.
  • Having “sometimes-JSON-with-comments” in libraries is seen as ambiguous and error-prone unless clearly separated.

Data Format vs. Config/File Format

  • Distinction raised: JSON as a wire/data format shouldn’t have comments; JSON as a human-edited file format arguably should.
  • Some say if you need comments and other niceties, JSON is simply the wrong tool for config.

Alternatives and Extensions

  • JSON5, JSONC, JWCC, HuJSON, and similar aim to formalize “JSON plus comments/trailing commas.”
  • Other formats are proposed for human-friendly structured data: YAML (controversial for ambiguity and complexity), TOML, EDN, various niche configs, and protobuf text format.
  • Some prefer sticking to strict JSON and encoding commentary as explicit fields to keep semantics visible and machine-processable.