JSON Comments

Beginner
4 min read
Updated: Nov 2026
3 examples
JSON comments tutorial — no // comments in strict JSON
Definition

Definition and Usage

Strict JSON does not allow line or block comments (// and /* … */). Calling JSON.parse on that text throws a SyntaxError.

JSON is data only—so every parser reads the same structure. Put notes in docs, in a string field named _comment, or (for schemas) in $comment.

Quick rule.

Note in data → use an _comment field. Schema editor note → JSON Schema $comment. Editor-only // → that is JSONC, not JSON.

Compare

Valid vs Invalid

Side by side: a note stored as data is fine; a real comment token is not.

Valid — note as data
JSON
{
  "_comment": "demo user",
  "name": "Ada"
}

Parses with JSON.parse. The note is just another string property.

Invalid — real comment
Not JSON
{
  // not allowed
  "name": "Ada"
}

Fails strict JSON. Same for block comments like /* … */ before or inside the text.

Options

What to Use Instead

  • _comment field Safe for any JSON file or API payload
  • README / OpenAPI Keep the data file pure JSON
  • Schema $comment Editor notes inside a JSON Schema (draft 7+)
  • JSONC / JSON5 Local config only — not strict JSON on the wire
Code

Examples

Use View Output for a quick result, or Try It Yourself to edit and run in the browser.

Example 1 — Comments Fail

JSON.parse rejects // comments.

JSON
// Invalid JSON text (has a // comment)
const text = `{
  // not allowed in JSON
  "name": "Ada"
}`;

try {
  JSON.parse(text);
} catch (err) {
  console.log(err.name + ": " + err.message);
}
Try It Yourself

How It Works

  1. The text looks like JavaScript, but it is not strict JSON.
  2. JSON.parse hits // and throws.
  3. Remove the comment (or use a data field) to make it valid.

Example 2 — Use a _comment Key

Store the note as a normal string property.

JSON
const data = {
  _comment: "Demo user",
  name: "Ada",
  id: 1
};

console.log(data.name);
console.log(data._comment);
Try It Yourself

How It Works

  1. _comment is just another property.
  2. No parse step needed — this is a normal object.
  3. Ignore or strip _comment if clients do not need it.

Example 3 — Schema $comment

Leave an editor note on a small schema object.

JSON
const schema = {
  $comment: "Tutorial sample schema",
  type: "object",
  properties: {
    id: { type: "integer" }
  }
};

console.log(schema.$comment);
console.log(schema.type);
Try It Yourself

How It Works

  1. $comment is a normal property on the object.
  2. In JSON Schema, it is for editors only.
  3. It must not change validation behavior.

Frequently Asked Questions

No. Strict JSON does not allow // or /* */ comments. JSON.parse() throws a SyntaxError if it sees them.
Use a normal string field such as "_comment". It is valid data; ignore the key if you do not need it.
$comment is a schema keyword for notes to schema editors. It is not a general JSON comment syntax for API payloads.
Yes in the editor (JSON with Comments), but that text is not strict JSON. Strip comments before JSON.parse or before shipping to APIs.

Next: JSON.parse()

Parse valid JSON text into JavaScript values.

JSON.parse() tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

AWS Certified Developer – Associate (Credly)

12 people found this page helpful

JSON Rules JSON.parse()