How to Add Comments in JSON: JSONC, JSON5, and 4 Practical Workarounds

JSON is intentionally designed not to support comments. This makes sense for machines, but it can be inconvenient for developers who want to annotate configuration files, document fields, or leave notes for teammates.

In this article, you will learn practical ways to include comments in or around JSON, including JSONC, JSON5, and several safe workarounds that preserve compatibility.

Why JSON Doesn’t Support Comments

JSON follows a strict specification (RFC 8259).
To stay lightweight and machine-friendly, it excludes comments entirely.
However, real-world use cases often require optional annotations—especially for config files.

Below are effective techniques to work around this limitation.

Workaround 1: Store Comments as Data

You can embed comments as part of the JSON structure.

{
  "_comment": "This configuration controls application behavior",
  "enableFeature": true
}

Advantages:

• Valid JSON everywhere
• Comments preserved when parsed
• No tooling changes required

Downsides:

• Comments become part of your data model
• May require filtering at runtime

Multi-Key Comments Example

{
  "_comment_database": "Settings related to DB connection",
  "db": {
    "host": "localhost",
    "port": 3306
  }
}

Use this method when full compatibility is the priority.

Workaround 2: Add Multi-Line Comments as Strings

If you want longer annotations, embed them as string fields.

{
  "_note": "Line 1: This is a long comment.\nLine 2: It spans multiple lines.\nLine 3: JSON won't break."
}

Or use an array of comment lines:

{
  "_notes": [
    "This config file controls login access",
    "Remember to rotate keys every 90 days"
  ]
}

Readable and flexible, but still part of the data.

Workaround 3: Attach Comments to Multiple Keys

If each field needs an explanation, you can group comments using a separate key map.

{
  "username": "admin",
  "password": "secret",

  "_comments": {
    "username": "Admin login username",
    "password": "Do NOT commit real credentials"
  }
}

Useful when documenting many fields in a config file.

JSONC: Using JSON with Comments (Supported in VS Code)

JSONC (JSON with Comments) is a JSON extension used by VS Code and some configuration tools.

It allows:

Single-line comments

// Server configuration
{
  "port": 8080,
  "debug": true
}

Multi-line comments

/*
  Database settings
  Adjust only if necessary
*/
{
  "host": "localhost",
  "port": 3306
}

Pros:

• Human-friendly
• Fully supports comments
• Widely used in development tools

Cons:

• Not valid JSON
• Requires JSONC-aware parsers

Use JSONC when your environment explicitly supports it (VS Code settings, some CLI tools, etc.).

JSON5: A More Flexible JSON Alternative

JSON5 expands JSON syntax to be more developer-friendly.

Features:

• Single-line // comments
• Multi-line /* ... */ comments
• Unquoted keys
• Trailing commas

Example:

{
  // Application mode
  mode: "production",

  /* Enable detailed logs
     for debugging */
  debug: false,
}

Ideal for configuration files where readability matters.

Summary

JSON itself does not allow comments, but you still have several reliable approaches depending on your environment and requirements.

4 Ways to Add Comments in Practice

1. Store comments as data
   → Maximum compatibility, no special tools required
2. Use string fields for multi-line comments
   → Best for long explanations
3. Maintain a separate comment map for multiple keys
   → Useful for documenting structured config files
4. Use JSONC or JSON5
   → Best developer experience, but not strict JSON

By choosing the right method, you can keep your JSON files readable without sacrificing compatibility or safety.