Can comments be used in JSON?

Can Comments Be Used in JSON? Understanding JSON's Strict Syntax

Explore whether JSON officially supports comments, why it doesn't, and common workarounds for adding descriptive notes to your data structures.

JSON (JavaScript Object Notation) is a lightweight data-interchange format that is easy for humans to read and write and easy for machines to parse and generate. It is built on two structures: a collection of name/value pairs (object) and an ordered list of values (array). While its simplicity is a key strength, it also leads to strict rules regarding its syntax. One common question developers encounter is whether comments can be included directly within JSON files.

The Official Stance: No Comments in JSON

According to the official JSON specification (ECMA-404 and RFC 8259), comments are explicitly not allowed. This design choice was made to keep the format as simple and unambiguous as possible, focusing solely on data representation. The creator of JSON, Douglas Crockford, intentionally omitted comments to prevent potential interoperability issues and to ensure that JSON remains a pure data format, free from any processing instructions or metadata that might be misinterpreted by different parsers.

{
  "name": "John Doe",
  // This is a comment - WILL CAUSE ERROR!
  "age": 30,
  "city": "New York"
}

An example of invalid JSON with a comment.

Why the Strictness? Simplicity and Interoperability

The decision to exclude comments from JSON stems from its core philosophy: to be a data serialization format, not a configuration file format or a programming language. Comments, while useful for human readability, can introduce complexity for parsers. Different parsers might handle comments differently (e.g., ignoring them, stripping them, or even treating them as data if not properly escaped), leading to inconsistencies across systems. By disallowing comments, JSON ensures that any valid JSON document will be parsed identically by any compliant JSON parser, promoting maximum interoperability.

flowchart TD
    A[JSON Specification] --> B{Allow Comments?}
    B -- No --> C[Strict Data Format]
    C --> D[Ensures Interoperability]
    C --> E[Simplifies Parsers]
    B -- Yes (Hypothetical) --> F[Potential Parser Inconsistencies]
    F --> G[Reduced Interoperability]
    F --> H[Increased Parser Complexity]

Decision flow for JSON's comment exclusion.

Workarounds for Adding Descriptive Notes

While direct comments are forbidden, there are several common strategies to add descriptive information to your JSON data without violating the specification. These methods involve treating the comments as part of the data itself, which requires your application to understand and handle these special fields.

1. Using Special Keys for Metadata

One common approach is to introduce specific keys, often prefixed with an underscore or a similar convention, to hold descriptive text. Your application can then simply ignore these keys when processing the actual data.

{
  "_comment_user_info": "This section contains details about the user's profile.",
  "name": "Jane Doe",
  "age": 28,
  "_note_status": "Status indicates account activity level.",
  "status": "active"
}

JSON with descriptive notes using special keys.

2. External Documentation or Configuration

For more extensive documentation or comments that apply to the entire file or large sections, it's often best to keep them separate from the JSON data itself. This could be a README file, a dedicated documentation system, or even a separate configuration file that describes the JSON structure.

3. Pre-processing or Post-processing

If you absolutely need comments for development but want clean JSON for production, you can use build tools or scripts to strip comments before deployment. Tools like strip-json-comments (for Node.js) or custom scripts can remove C-style comments (//, /* */) from JSON-like files, allowing you to write comments during development.

const stripJsonComments = require('strip-json-comments');
const fs = require('fs');

const jsonWithComments = fs.readFileSync('config_dev.json', 'utf8');
const cleanJson = stripJsonComments(jsonWithComments);

fs.writeFileSync('config_prod.json', cleanJson);

Example of stripping comments from a JSON file using Node.js.