Need help with your JSON?

Try our JSON Formatter tool to automatically identify and fix syntax errors in your JSON. JSON Formatter tool

Handling Comments in JSON (Even Though They're Not Supported)

One of the common frustrations developers face when working with JSON is the lack of native support for comments. Unlike many configuration formats and programming languages, JSON has no built-in comment syntax. This limitation can make JSON files harder to maintain, especially for configuration settings or data that requires explanation. This article explores why JSON doesn't support comments, and provides practical workarounds for including comments or documentation in your JSON files.

Why JSON Doesn't Support Comments

Douglas Crockford, who formalized the JSON specification, intentionally excluded comments from JSON for several reasons:

Simplicity: The absence of comments keeps the JSON format and its parsers simpler
Data interchange focus: JSON is primarily designed for data interchange between applications, not as a configuration format
Interoperability: Excluding comments reduces the chance of incompatibility between different JSON implementations
Prevention of abuse: Comments could potentially be misused for directives that affect processing

As Crockford explained: "I removed comments from JSON because I saw people were using them to hold parsing directives, a practice which would have destroyed interoperability."

Common Workarounds for JSON Comments

Despite the lack of official support, developers have devised several approaches to include comments or documentation within JSON:

1. Using Comment Properties

The most straightforward approach is to create dedicated properties for comments within your JSON objects:

Using comment properties:

{
  "_comment": "Configuration settings for the application",
  "apiEndpoint": "https://api.example.com",
  "timeout": 30,
  "retryCount": 3,
  "features": {
    "_comment": "Feature toggle settings for each module",
    "newUI": true,
    "betaFeatures": false
  }
}

This approach is straightforward but adds overhead to your JSON size and requires applications to ignore these special properties.

2. Using Metadata Properties

A more structured approach is to include a dedicated metadata section that contains documentation:

{
  "metadata": {
    "description": "User preferences configuration",
    "version": "1.2.0",
    "lastModified": "2023-04-15",
    "notes": "Added new theme options"
  },
  "settings": {
    "theme": "dark",
    "notifications": true,
    "autoSave": false
  }
}

3. Using Adjacent Documentation

For many use cases, the best solution is to store documentation separately from the JSON itself:

README files: Keep a separate markdown file alongside your JSON
Schema documentation: Use JSON Schema to document the expected structure and values
Code comments: If the JSON is embedded in code, use the host language's comment syntax
External documentation: Reference more comprehensive documentation elsewhere

Using JSON5 or JSONC When Comments Are Essential

If comments are absolutely essential for your use case, consider using extended JSON formats that support comments:

1. JSON5

JSON5 is an extension of JSON that aims to be more human-friendly, including support for comments:

{
  // This is a single-line comment
  "name": "JSON5 Example",
  "version": "1.0.0",
  /* This is a
     multi-line comment */
  "description": "A configuration file with comments",
  "enabled": true,
}

JSON5 adds several features beyond standard JSON, including comments, trailing commas, and unquoted keys.

2. JSONC (JSON with Comments)

JSONC is another extension that supports comments while staying closer to the original JSON format:

{
  // Settings for development environment
  "server": {
    "port": 3000,
    "host": "localhost"
  },
  /* Security configuration
     with detailed explanation */
  "security": {
    "enableAuth": true,
    "tokenExpiration": 3600
  }
}

JSONC is commonly used in development tools like Visual Studio Code for configuration files.

Important Note:

While JSON5 and JSONC are useful for development and configuration files, they should not be used for data interchange between different systems unless all systems explicitly support these formats. For interchange, stick to standard JSON.

Pre-processing and Post-processing Approaches

Another approach is to work with comments during development, but strip them out when generating the final JSON:

1. Pre-processing

Author in JSONC or JSON5 with comments
Use a tool to strip comments before deploying
Examples: strip-json-comments (Node.js), jq (command line)

2. Using JSON-generating Tools

Generate JSON from formats that do support comments (YAML, TOML)
Document in the source format, then convert to JSON for deployment
Example workflow: maintain in YAML with comments → convert to JSON for production

# YAML source with comments
# This is the main configuration file
server:
  # Development server port
  port: 8080
  # Bind to all interfaces
  host: "0.0.0.0"

# Security settings
security:
  enabled: true
  # Token validity in seconds
  tokenLifetime: 3600

Best Practices for Documenting JSON

Be consistent: Choose one approach and use it consistently throughout your project
Consider the context: For configuration files, JSON5 might be appropriate; for APIs, use standard JSON with separate documentation
Validate before deployment: Ensure your JSON is valid after removing comments or converting from other formats
Use JSON Schema: Create a schema that documents your JSON structure formally
Keep documentation up-to-date: Ensure your comments or documentation are maintained when the JSON structure changes

JSON Schema for Documentation

JSON Schema provides a powerful way to document JSON structures while also enabling validation:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "User Configuration",
  "description": "Settings for user preferences in the application",
  "type": "object",
  "properties": {
    "theme": {
      "type": "string",
      "description": "UI theme preference (light or dark)",
      "enum": ["light", "dark", "system"]
    },
    "notifications": {
      "type": "boolean",
      "description": "Whether to enable push notifications"
    },
    "refreshInterval": {
      "type": "integer",
      "description": "Data refresh interval in seconds",
      "minimum": 30,
      "maximum": 3600
    }
  },
  "required": ["theme", "notifications"]
}

Need help with your JSON?

Try our JSON Formatter tool to automatically identify and fix syntax errors in your JSON. JSON Formatter tool