Blog

Can Comments Be Used in JSON? Explained

4 min read
4 minutes ago

JSON is everywhere. It’s used in web apps, APIs, databases, and even your favorite games. It looks like a simple list of keys and values wrapped in curly braces. But one big question keeps popping up—can you add comments in JSON?

TLDR (Too Long, Didn’t Read)

Nope, JSON doesn’t support comments. It’s designed to be a lightweight, data-only format. If you try to add traditional comments like // this is a comment, your JSON might break. But don’t worry—we’ll show you clever workarounds that won’t crash your code!

What Is JSON Anyway?

JSON stands for JavaScript Object Notation. Even though it has “JavaScript” in the name, you can use it with almost any programming language—it’s that flexible!

JSON is used to store and exchange data. It looks like this:

{
  "name": "Waffles",
  "age": 3,
  "breed": "Golden Retriever"
}

Nice and clean, right? But wait, where’s the comment telling us that “age” is in dog years?!

Why JSON Doesn’t Allow Comments

  • Minimalism: JSON was built to be simple and readable. Adding comments makes it messier.
  • Parse errors: Browsers and tools that read JSON files expect strict formatting. A rogue comment can crash the whole thing.
  • Security concerns: In some applications, comments could be abused to hide malicious content or mislead users.

These reasons mean that if you put // this is a comment or /* comment */ into a JSON file, the parser will throw a tantrum (or just toss an error).

Let’s Try It

Here’s a commented JSON file:

{
  // this is the user's name
  "name": "Alice",
  /* this is the user's age */
  "age": 25
}

Looks fine? Try loading that in your favorite code tool or a validator. It won’t work!

But I Really Need Comments!

Don’t worry, we’ve got tricks! While you can’t add actual comments, you can fake them.

1. Use a Dummy Field

Add a key like "_comment" to your JSON:

{
  "name": "Alice",
  "age": 25,
  "_comment": "This is the user's age in human years."
}

This won’t bother the parser, and your data is still valid. Just don’t try to use _comment like real data in your app—they’re for your eyes only.

2. Keep Comments Outside JSON

Sometimes, the cleanest solution is not to tamper with JSON at all. Instead, place comments in the file that uses the JSON—like your JavaScript code, server config, or documentation.

// Load user data from users.json
const user = loadJSON('users.json');

3. Remove Comments Automatically

Want to comment while working and clean things up later? Use a tool that strips comments before deploying.

For example, JSON5 or json-strip-comments lets you add comments during development. Before release, it removes them, leaving clean JSON behind.

JSON Alternatives That Support Comments

If you find JSON too strict, consider using another format.

  • YAML – Super flexible and supports comments with #
  • JSON5 – A JSON upgrade that supports comments and trailing commas
  • TOML – Used in tools like Rust’s Cargo, and friendly for humans

Here’s an example in YAML:

# This is the user's data
name: Alice
age: 25

So readable. So nice. So… not JSON.

Why Was JSON Made This Way?

Doug Crockford, the creator of JSON, wanted simplicity. He made JSON for data transport, not code readability or documentation. By cutting out extra characters like comments, he kept JSON fast and clean.

Like plain toast: nothing fancy, but it gets the job done.

But I See Comments in Some JSON Files?

Aha! You might have seen them in config files labeled .jsonc (JSON with Comments). These don’t follow true JSON rules but are used in special apps like VS Code.

If you try reading them with a strict JSON parser, they’ll fail. So be careful!

Tips for Dealing With Comment-Free JSON

  • Use _comment fields—they keep notes right with your data
  • Create good documentation—always helpful when handing off files
  • Use tools that help—like JSON5 when you need flexibility
  • Validate often—always check your JSON is clean before shipping

Let’s Recap

To answer the big question: No, JSON does not support comments. It’s meant to be simple and unforgiving. But you have workarounds:

  • Add dummy keys like "_comment"
  • Keep notes in separate files
  • Use alternative formats when possible

Final Thoughts

Working with JSON can feel like cooking with no spices. No comments? Really? But with some clever techniques, you can still stay organized and keep your code happy.

Just remember: JSON wants to keep things clean, fast, and error-free. If you need fancier features, YAML or JSON5 might be the better flavor for you.

Now go out there and comment the world—just, maybe not inside your JSON files!