What is JavaScript Object Notation with Comments (JSONC), and is it any better than JavaScript Object Notation (JSON)?

In this article we will explore:

• What JavaScript Object Notation (JSON) is — its origins, syntax, strengths and limitations.
• What JSONC (sometimes called “JSON with comments”) is — how it extends JSON, how it came about, how it works.
• A detailed comparison of JSON vs JSONC: use-cases, compatibility, tooling, pros & cons.
• My view on whether JSONC is better than JSON (and in what contexts).
• Best-practice guidance for when to use JSON or JSONC (or perhaps other formats altogether).

1. Understanding JSON

1.1 Background and Purpose

JSON stands for JavaScript Object Notation. It was originally popularised (though not exactly invented) by Douglas Crockford and others as a lightweight, human-readable data‐interchange format.
Key points:

• JSON is text-based, language-independent (despite the “JavaScript” in its name), and widely supported.
• Its goal is to represent structured data (objects, arrays, strings, numbers, booleans, null) in a way that is easy for machines to parse and humans to read.
• Because of its popularity, many APIs, configuration files, NoSQL documents, etc., use JSON.

1.2 Syntax and Restrictions

The syntax of JSON is fairly simple, but deliberately so. For example:

{
  "firstName": "John",
  "age": 30,
  "married": false,
  "children": ["Alice", "Bob"],
  "address": {
    "street": "21 2nd Street",
    "city": "New York"
  },
  "spouse": null
}

This example shows objects ({ … }), arrays

 ([ … ]), strings, numbers, booleans,

 null, nested objects. This corresponds

 to the typical JSON definition.

Important restrictions / design decisions:

• JSON does not allow comments (// … or /* … */). The spec deliberately omitted comments.
• JSON keys (object property names) must be quoted strings. Values must adhere to the allowed types.
• Ordering of properties is not significant (though many systems preserve insertion order).
• Simplicity is a virtue: minimal grammar, easy parsing.

1.3 Why JSON Doesn’t Support Comments

While at first glance comments seem harmless (and indeed valuable from a human-readability standpoint), JSON’s specification purposely excluded them. The reasoning includes:

• Having comments may encourage using JSON as a programming/configuration language rather than a pure data representation, which can complicate parsing, interoperability, and standardization.
• Many parsers and platforms expect the data to be purely information, not annotated for humans; comments introduce variance in whitespace, potential ambiguity or misuse.
• Douglas Crockford stated that comments were removed so that JSON would remain clean, unambiguous, and easily machine-parsable.

Hence, for many years, JSON remained comment-free by design, and that has strong advantages: universal tooling support, well-understood behaviour, minimal legacy surprises.

1.4 Strengths and Limitations of JSON

Strengths

• Ubiquitous: virtually every programming language supports JSON parsing/generation.
• Simple and lightweight: minimal syntax overhead, efficient to parse.
• Ideal for data interchange (APIs, logs, config files in many contexts).
• Very well documented and standardized (e.g., RFC 8259).

Limitations

• Lack of comments means less ability to annotate or explain fields inline. That can hurt maintainability of large 
• configuration files or complex data structures.
• Sometimes JSON’s strict syntax (quoted keys, no trailing commas, etc.) can feel verbose or restrictive if you compare to more relaxed formats (YAML, TOML, etc.).
• Because comments are not allowed, developers often resort to work-arounds (e.g., use a key like _comment or embed documentation elsewhere) which may be messy.

2. Introducing JSONC (JSON with Comments)

2.1 What is JSONC?

JSONC is a variation or superset of JSON that allows comments. In other words: you 

can write JSON-style data but include JavaScript-style comments (// … and /* … */). The format is often informally called “JSON with Comments”. As one description puts it:

“JSONC (JSON with Comments) is an extension of JSON (JavaScript Object Notation) that allows comments within JSON data.”

It is not an official standard in the sense 

of JSON (though there is a draft specification). Tools and editors (most notably Visual Studio Code) support it for configuration files.

For example:

{
  // This is a single-line comment
  "name": "Sara",  /* Inline comment 

about name */
  "age": 30,
  "skills": [
    "Python",
    "JavaScript"
  ] /* comment after array */
}

From w3resource’s example.

2.2 Origin and Use Cases

The JSONC format emerged because developers wanted the simplicity and broad support of JSON and the human-friendliness of inline comments/annotations. Some salient points:

• In the context of VS Code, configuration files like settings.json, launch.json are treated as “JSON with comments” even though their extension is .json. VS Code supports the “jsonc” language mode.
• The GitHub project “JSONC: JSON with Comments specification” exists as
•  an effort to formalize this.
• Some parser libraries (in Go, Python, etc.) support JSONC or equivalent: you can parse data that has comments by 
• stripping them or using a dedicated parser.

So JSONC is particularly well suited for configuration files, developer-facing artifacts, and scenarios where the file may benefit from inline explanations or be 

edited by humans.

2.3 Syntax Differences Compared to JSON

What JSONC allows that JSON disallows:

• Single-line comments starting with //.
• Multi-line/block comments using /* … */.
• Possibly trailing commas and unquoted keys (depending on the implementation) but strictly speaking JSONC specification may or may not allow all of those; the primary enhancement is comments. For example: the spec states that trailing commas are not permitted by default in JSONC.
• JSONC is backward-compatible in the sense that any valid JSON is valid JSONC (because comments are ignored). But the reverse is not true: a JSONC file with comments is not valid JSON unless comments are removed.

2.4 Implementation & Tooling Considerations

• Many editors treat “.jsonc” as a language mode for “JSON with comments” (VS Code for example).
• Parsers: to use JSONC in production, you often need a JSONC-aware parser (that strips comments) or a preprocessing step that removes comments before handing data to a standard JSON parser. For example, the spec at jsonc.org lists node-jsonc-parser by Microsoft.
• Interoperability: Because not all tools accept comments in JSON, you may need to ensure compatibility when exchanging data or using generic libraries. Some tools will throw errors if comments are present (treating them as invalid JSON). This is a key caution.

3. Side-by-Side Comparison: JSON vs JSONC

Let’s compare them across several dimensions.

Dimension	JSON	JSONC
Standardization & Ecosystem	Very mature, standardized (RFC 8259, ECMA etc)	Less formal standard; more “adopted practice” rather than universally guaranteed. JSONC spec exists as a draft.
Compatibility	Very high: most parsers handle JSON without issue.	Lower if comments are present: standard JSON parsers will generally fail or treat comments as errors. Workarounds needed.
Human-readability / Maintainability	Good but limited: no comments means less ability to annotate inline.	Better for human editing: comments allow explanation of fields, context, rationale.
Use for Config Files & Development	Works, but sometimes regarded as “bare” because no comments allowed. Developers use _comment fields or external docs.	Ideal for config files where developers need to annotate items, jot down rationale, toggle features etc.
Parsing Overhead / Simplicity	Very simple grammar; efficient parsing in many languages.	Slightly more complex: parser must ignore/strip comments, might support additional syntax. This can introduce complexity or edge-cases.
Interoperability / Data Exchange	Excellent for machine‐to‐machine interchange: no surprises, minimal extras.	Riskier: if receiving system expects strict JSON and gets comments, may fail. So less safe for general interchange without coordination.
Best Practice for Production Data	Strong: Data payloads, API responses, logs — JSON is appropriate.	More suited to development / configuration phase rather than critical interchange unless all parties support it.
Size / Transmission Overhead	Lean (no comment “noise”).	Slightly larger (comments add bytes) and if comments are kept in production, could bloat transmitted data.
Flexibility	Minimal. It sticks to data only.	More flexible (annotations allowed), but with that comes trade-offs.

3.1 When JSONC “Wins”

JSONC shows its strength particularly when:

• You have configuration files that will be read and maintained by humans (developers, operations engineers). You want inline notes like “// disable this in staging” or “/* we fallback to X if Y fails */”.
• You want to keep the file in a consistent format (JSON-style) but still wish for comments during development.
• You are in a closed ecosystem (e.g., within your application) where you control parsing, so you can ensure comment-support and strip them or parse accordingly.

Example: The article from w3resource shows using JSONC to annotate configuration sections, e.g.,

{
  // Application settings
  "app": {
    "name": "MyApp",
    "version": "1.0.0"
  },
  /* Database configuration */
  "database": {
    "host": "localhost",
    "port": 3306,
    "user": "admin",
    "password": "secret" // 

Change this to your actual password
  }
}

This is much easier to manage for a human than embedding explanatory text elsewhere.

3.2 When JSONC “Falls Short”

Nevertheless, JSONC has some drawbacks relative to plain JSON:

• If you forget to strip comments before production or send the file to a system expecting standard JSON, it may fail. For example, as one Medium article warns:

“Temporary Use of JSONC … but it isn’t compatible with standard JSON parsers.”

• If you treat JSONC as “just JSON plus comments” without enforcing good discipline, you may accumulate comment clutter or stale annotation that confuses readers.
• It may complicate toolchains: linters, schemas, validators might expect strict JSON unless configured.
• Data interchange between heterogeneous systems may be less robust if there is no guarantee that all parties support JSONC.

3.3 Performance and Parsing Considerations

From the parsing perspective: JSONC parsers must handle stripping or ignoring comment tokens and then parse the remaining JSON.

 That means:

• Slight extra parsing overhead (though often negligible) compared to plain JSON.
• Possibility of parser divergence or subtle bugs if the comment-stripping logic is imperfect.
• If comments are included in production data, one must verify that downstream systems can handle them (or that they are removed).

From file size point of view: Comments add extra bytes; tiny for most config files but for very large data interchange it may matter.

3.4 Tooling & Ecosystem in Practice

• Many editors recognise “jsonc” as a language mode; example: VS Code allows configuring file associations so that *.json files may be treated as jsonc and allow comments.
• The JSONC specification (jsonc.org) lists parser implementations for many languages: JavaScript/TypeScript, Go, Python, C++, etc.
• However: Many generic JSON-tools,
•  linters, API services do not accept comments in JSON — meaning you may need to convert JSONC → JSON (strip comments) before usage. This adds a build/pre-processing step. Articles such as the one by freeCodeCamp explain how to add comments, but emphasise that standard JSON parsers will reject them.

4. Is JSONC Better than JSON?

The answer: “It depends.” JSONC is not strictly “better” in all contexts; rather, it is better in certain contexts and less appropriate in others. I’ll break this down.

4.1 Criteria for “Better”

We might define “better” in terms of: readability, maintainability, developer experience, compatibility, performance, safety for data interchange.

4.2 Scenarios Where JSONC Offers Clear Advantages

For configuration files and human-maintained data sets, JSONC often offers improvements over plain JSON:

• The ability to add inline comments helps developers understand why something is configured a certain way, rather than just what.
• When maintaining large JSON config files (multiple thousands of lines), comments reduce the “black-box” nature of the data.
• During development, JSONC allows iterative changes, toggles, explanation of alternatives (e.g., “// disable feature for now”), improving developer experience.
• If you control the environment (editor + parser), you gain the benefits of JSON (clear, structured, machine-readable) plus the human-friendly annotation layer.
  Therefore — in the realm of configuration files, internal tooling, developer-facing JSON — JSONC is arguably better than standard JSON.

4.3 Scenarios Where JSON (without comments) is Preferable

Conversely, there are many contexts where plain JSON is preferable (and arguably “better”):

• When you’re exchanging data between systems, especially heterogeneous ones where you cannot guarantee comment-support. Using strict JSON ensures maximum compatibility.
• In production API responses, logs, data stores: minimal overhead, maximal parsing robustness. JSONC’s added complexity (comments, preprocessing) may introduce risk.
• When performance and simplicity matter: JSON’s simpler grammar means simpler parsers, less chance of variance, fewer edge cases.
• When you want to play safe with standardization: JSON is widely 
• covered by tools, validators, language libraries; JSONC may require custom tooling or pre-processing.
  Thus — for machine-to-machine interchange, public APIs, production data stores — plain JSON remains “better”.

4.4 My Verdict and Guidance

So how do I summarise?

• Use JSON when you need robust, interoperable, standard, minimal-overhead data interchange. If comments are not essential to the use-case, lean toward plain JSON.
• Use JSONC when your file is primarily human-edited, developer-maintained, benefits from annotation and explanation, and you control the toolchain so that comment-support is assured.
• Be cautious: if you choose JSONC for broader interchange, ensure all consumers support it (or strip comments before sending).
• Adopt good practice: maybe keep production data trimmed (comments removed) and keep comments for development versions or editable config layers.

In short: JSONC is not a replacement for JSON in all cases; it is a complementary tool. In its proper niche it is “better”, but we should not view it as universally superior.

5. Best Practices & Pitfalls

Here are some practical guidelines for working with JSON and JSONC:

5.1 When Using JSONC

• Clearly document in your project that you are using .jsonc (or jsonc mode) and ensure your parsers support comments.
• If you will send the data onward, ensure comments are stripped or your receiver supports them.
• Avoid relying on comments for critical logic — comments should explain “why”, not change semantics.
• Keep comments readable but not verbose or unnecessary (comments themselves must be maintained).
• Use consistent formatting (indentation, comment placement) so that version-control diffs remain meaningful.
• Consider separating “human commentary” from “machine data” if comments become heavy; sometimes external documentation may be cleaner.

5.2 When Staying with Plain JSON

• Accept that you won’t have inline comments — plan for documentation elsewhere (README, schema comments, etc.).
• Use schema validation (JSON Schema) or code comments to explain fields if required.
• Keep the data lean, avoid extraneous keys (like _comment) unless you control both ends of the exchange.
• Ensure parsers, consumers follow JSON spec strictly (or know tolerances), to avoid surprises.

5.3 Pitfalls to Watch

• Using comments in JSON without stripping them causes parse errors in many tools. For example:

  “Standard JSON parsers will reject files with comments like // or /* … */.”

• Using JSONC in public APIs or third-party data transfer may cause compatibility issues.
• Relying on comments means that if comments become stale (e.g., after refactoring), they may mislead developers.
• Over-commenting or embedding large chunks of logic explanation in config files can clutter and distract from the data itself.
• Failing to version control comment format or parser behaviour — note that JSONC is not as strictly standardized as JSON, so behaviour may vary across libraries.

6. Illustrative Examples

Example A: Plain JSON

{
  "server": "localhost",
  "port": 8080,
  "useTLS": true
}

No comments. If someone wonders why 

useTLS is true, they must look at documentation or code.

Example B: JSONC

{
  // Primary server configuration
  "server": "localhost",
  "port": 8080,  // typical http port 

for development
  "useTLS": true  /* We enable TLS by

 default in production */
}

Here a developer reading the file immediately gets context: the comment explains purpose and environment intent.

Example C: Mixed Context 

(Production vs Development)

One pattern: keep a config.jsonc file with comments during development, and at build time strip the comments into a config.json for production deployment. That gives the best of both worlds: human-friendly development file, clean machine file for runtime. Many

 toolchains adopt this strategy.

7. Summary

To summarise:

• JSON is a very successful, standard, lean data‐interchange format — excellent for machine-to-machine exchange, APIs, logging, storage.
• JSON’s major limitation for some users is the inability to embed comments/annotations, which reduces human readability and maintainability in certain contexts.
• JSONC (JSON with Comments) fills that gap by allowing JavaScript-style comments inside JSON-style files, making them more readable and maintainable for developers.
• However, JSONC comes with trade-offs: compatibility risks, requirement for proper parsing tooling, potential bloat.
• Whether JSONC is “better” depends entirely on context: for config files and human-edited data, yes — JSONC often wins. For broad data interchange, production payloads, strict standards, plain JSON remains the safer and “better” choice.
• The pragmatic approach: choose the right tool for the job, understand the ecosystem you operate in, and apply best practices (strip comments if necessary, maintain documentation, ensure tooling support).

8. Final Thoughts

As developers and architects, we often find ourselves choosing between formats and tools. It’s tempting to treat the “newer” option as automatically superior — but the key is to match format to purpose. In the case of JSON vs JSONC:

• If you’re building a library, API, or service that will be consumed broadly, stick to standard JSON.
• If you’re writing configuration files that people will edit, comment, revisit, using JSONC can significantly improve maintainability and clarity.
• You might even adopt a hybrid workflow: JSONC for development/editing, export to JSON for runtime.
  One last note: documents like the JSONC specification remind us that the idea of “data formats” is evolving. What matters ultimately is clarity (for humans) and interoperability (for machines). JSONC is a thoughtful extension of JSON when human-readability is a first-class concern.