JSON Comments: Why They Don't Exist and How to Work Around It

One of the first frustrations developers encounter when working with JSON is the complete absence of comment support. Unlike YAML, XML, TOML, and every programming language, standard JSON (RFC 7159 / RFC 8259) has no syntax for comments. This article explains why, and provides 5 practical workarounds with code examples and tools.

Why Doesn't JSON Support Comments?

The decision was deliberate. Douglas Crockford, who popularized JSON, explains that comments are often used as a crutch for poor data structure design. Specifically:

• Comments are metadata — JSON is a data interchange format, not a document format. Data should be self-describing through meaningful key names.
• Parsing complexity — Comments complicate parsers and create edge cases (nested comments, comment delimiters in strings, etc.).
• Interoperability — If one tool preserves comments and another strips them, the data changes unexpectedly.
• Security — Comments could theoretically be used to smuggle data or bypass validators.

"JSON is a data format, not a programming language. Data should not need comments." — Douglas Crockford

Workaround 1: Use JSONC (JSON with Comments)

JSONC (JSON with Comments) is an informal extension that supports JavaScript-style comments. Key differences from standard JSON:

• // single-line comments
• /* */ multi-line comments
• Trailing commas are often allowed

Important: JSONC is not standard JSON. Use it only with tools that explicitly support it (VS Code, many linters). Our JSONC to JSON converter strips comments for production use, and JSON to JSONC adds comment placeholders.

// This is a JSONC file — NOT valid JSON
{
  "name": "Alice",  // user's display name
  /* Age in years */
  "age": 30
}

Workaround 2: Use Special Key Conventions

Add metadata keys that serve as comments. Common conventions include:

{
  "_comment": "This file describes the user profile schema",
  "_description": "Name field must be non-empty",
  "name": "Alice",
  "//": "Age is optional, defaults to null",
  "age": 30,
  "//metadata": "This convention uses double-slash keys"
}

Pros: JSON remains valid. Any parser can read it.
Cons: Increases file size. Consumers must know to ignore these keys.

Workaround 3: Preprocess with Comment Stripping

Write JSON with comments during development, then strip them during build:

// Example: strip-comments.js (Node.js)
const fs = require('fs');
let content = fs.readFileSync('config.jsonc', 'utf8');

// Remove single-line comments
content = content.replace(/\/\/.*$/gm, '');
// Remove multi-line comments
content = content.replace(/\/\*[\s\S]*?\*\//g, '');
// Parse as JSON
const config = JSON.parse(content);

Our JSONC to JSON converter does this automatically in your browser.

Workaround 4: Use JSON Schema Descriptions

For API validation and documentation, JSON Schema provides a description field:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "The user's full display name, must be 1-100 characters",
      "minLength": 1,
      "maxLength": 100
    },
    "age": {
      "type": "integer",
      "description": "Age in years. Optional field, defaults to null.",
      "minimum": 0,
      "maximum": 150
    }
  },
  "required": ["name"]
}

Generate schemas from your JSON data with our JSON Schema Generator.

Workaround 5: Use JSON5

JSON5 is a superset of JSON designed to be more human-friendly. It adds:

• Comments (// and /* */)
• Unquoted object keys
• Single-quoted strings
• Trailing commas
• Leading decimal points (.5) and hexadecimal numbers (0xFF)

// This is JSON5
{
  name: 'Alice',      // unquoted key, single-quoted string, trailing comma
  age: 30,
  hex: 0xFF,          // hex number
}

Caveat: JSON5 is not widely supported. Use it only when you control both producer and consumer.

Which Workaround Should You Choose?

Workaround	Best For	Valid JSON?	Tool Support
JSONC	Dev config files (VS Code settings)	No	VS Code, ESLint, Prettier
Convention keys	Public APIs, data interchange	Yes	All tools
Preprocessing	Build pipelines, CI/CD	After stripping	Custom scripts
JSON Schema	API documentation, validation	Yes	Validators, docs
JSON5	Internal tools, personal projects	No	Limited

For most developers, using JSONC with VS Code for config files and convention keys for public APIs is the sweet spot. Use our JSONC to JSON converter to switch between formats.