Working with Comments in JSON5-Compatible Formatters

If your file contains // single-line or /* block */ comments, it is no longer standard JSON. It needs a formatter or parser that explicitly supports JSON5. That distinction is the main reason commented config files work in some tools but fail immediately in APIs, browser JSON.parse()calls, or older automation scripts.

JSON5 extends JSON with human-friendly syntax such as comments, trailing commas, single-quoted strings, and unquoted keys. Comments are one of its most useful features, but they only help if your workflow preserves them where needed and converts them away where strict JSON is required.

Quick Answer

• Standard JSON does not allow comments.
• JSON5 allows both // and /* ... */ comments.
• A JSON5-compatible formatter can read and format commented files, but a strict JSON formatter cannot.
• If you parse a commented file into an object and then stringify it again, the original comments usually do not survive.
• If the final destination is an API, a browser JSON parser, or a VBA JSON library, convert the file back to strict JSON before sending it downstream.

Why Standard JSON Doesn't Allow Comments

The original JSON specification deliberately omitted comments. Douglas Crockford, the creator of JSON, stated that he removed comments because he saw people using them to include parsing directives. His goal was to keep JSON purely a data format, free from implementation details or instructions within the data itself. While this decision keeps JSON simple and focused, it removes a useful feature for human readability and maintainability, especially for configuration files.

JSON5: JSON for Humans

JSON5 extends JSON with several features aimed at improving human readability. These include:

• Comments (single-line and multi-line)
• Trailing commas in objects and arrays
• Unquoted object keys (if they are valid identifiers)
• Single-quoted strings
• Multiline strings
• Reserved words as keys
• Other number formats (hexadecimal, positive/negative infinity, NaN)

For hand-edited config files, comments are usually the feature people care about most because they let you explain defaults, warnings, environment-specific settings, and migration notes right next to the data.

Which Comment Styles Work in JSON5

JSON5 supports the same two comment styles most developers already know from JavaScript:

1. Single-Line Comments (`//`)

These comments start with two forward slashes (`//`) and continue to the end of the line. They are useful for adding brief explanations or notes next to specific properties or values.

{
  "database": {
    "host": "localhost", // Database server address
    "port": 5432,        // Port number for connection
    "username": "admin"
    // Note: Password should be stored securely, not here!
  },
  "api": {
    "timeout": 5000      // API request timeout in ms
  }
}

2. Multi-Line Comments (`/* */`)

These comments start with `/*` and end with `*/`. They can span multiple lines and are ideal for more detailed explanations, descriptions of sections, or temporarily commenting out blocks of code.

{
  /*
    Application Configuration File

    This file contains settings for database connections,
    API endpoints, feature flags, etc.
    Please be careful when modifying this file.
  */
  "appSettings": {
    "appName": "My Awesome App",
    "version": "1.0.0"
  },
  /*
  "featureFlags": {
    "beta": true, // Temporarily disabled for production testing
    "new_dashboard": false
  },
  */
  "logging": {
    "level": "info" // Set logging level (debug, info, warn, error)
  }
}

What a JSON5-Compatible Formatter Actually Does

The phrase "JSON5-compatible formatter" can mean different things, and the difference matters if you care about comments.

• Strict JSON formatter: Rejects the file as soon as it sees comments, trailing commas, or other JSON5 syntax.
• JSON5 text formatter: Reads the commented source and rewrites spacing, indentation, and line breaks while keeping valid comments in place.
• Parse-and-stringify workflow: Reads the data into an object and writes it back out. This usually removes the original comments because comments are not part of the resulting data structure.

// Authored by a human
{
  // Retry failed uploads three times before surfacing an error
  retries: 3,
  timeoutMs: 5000,
}

{"retries":3,"timeoutMs":5000}

Benefits of Using Comments in JSON5

Adding comments to your JSON5 files offers several advantages:

• Improved Readability: Explain complex settings or data structures directly within the file.
• Easier Maintenance: Future users (including yourself) can quickly understand the purpose of different parts of the configuration or data.
• Self-Documenting: The file becomes its own documentation, reducing the need for separate documents (though complex systems may still require them).
• Temporary Disabling: Easily comment out configuration options or data entries without deleting them.

Best Workflow When Comments Matter

The safest pattern is to treat comments as authoring-time help, not as data that every downstream consumer must understand.

1. Author and review the file as JSON5 so comments stay close to the settings they explain.
2. Format and validate it with a tool that explicitly says it supports JSON5.
3. Convert it to strict JSON before sending it to systems that expect plain JSON.
4. Keep the commented source file if humans still need to maintain the configuration later.

This avoids the common mistake of assuming that because one editor accepts commented JSON, every parser in the pipeline will accept it too.

Using JSON5-Compatible Formatters and Parsers

To work with JSON5 files, you need tools that understand the JSON5 specification. Standard JSON parsers will throw errors when encountering comments or other JSON5 features.

Look for text editors, IDEs, and online formatters/validators that explicitly state support for JSON5. These tools will correctly parse, format, and validate your JSON5 files, including preserving or handling comments as appropriate.

In the JavaScript ecosystem, the official JSON5 tooling also supports validation and conversion. That is useful when your source file should stay commented, but your deployment artifact must be plain JSON.

# Validate a commented JSON5 file
json5 --validate config.json5

# Convert JSON5 to strict JSON
json5 -o config.json config.json5

Working with VBA and Other Strict JSON Tools

This is where many search users get stuck. A hand-edited file with comments may look fine in a JSON5-aware formatter, but Excel, Access, or older automation code often uses strict JSON libraries that expect plain JSON text.

A common VBA workflow uses a parser such as VBA-JSON to load JSON into nestedDictionary and Collection objects. That is a good fit for working with JSON objects in VBA, but it also means your input should already be strict JSON by the time it reachesParseJson.

' By this stage, comments should already be removed
Dim parsed As Object
Set parsed = JsonConverter.ParseJson(jsonText)

Debug.Print parsed("database")("host")

If your source config is commented JSON5, keep it as .json5, format and validate it with a JSON5-aware tool, then export a plain .json version for VBA, APIs, or any system that follows the normal JSON rules.

Tips for Effective Commenting in JSON5

• Be Concise: Comments should clarify, not clutter. Keep them brief and to the point.
• Explain the Why: Instead of just restating what the code does, explain why it does it or the purpose of a specific setting.
• Keep Them Updated: Outdated comments are misleading. Ensure comments are updated whenever the corresponding data changes.
• Use for Configuration: JSON5 is particularly useful for configuration files where human readability and notes are highly beneficial.
• Validate: Even with comments, always validate your JSON5 to catch syntax errors before using it.

Common Mistakes and Fixes

• Unexpected token `/` during parsing: You are using a strict JSON parser, not a JSON5 parser.
• Comments disappeared after formatting: Your workflow likely parsed the file into data and re-serialized it instead of preserving the source text.
• A browser, API, or import step rejects the file: Convert the file to strict JSON and remove JSON5-only features such as comments, trailing commas, single quotes, and unquoted keys.
• Your VBA script fails on a config file that looked valid in an editor:Validate the source as JSON5 first, then pass a converted plain JSON string into the VBA parser.

Conclusion

JSON5 comments are most useful when humans need to understand and maintain a file over time. They make local configuration, test fixtures, and reviewable settings files much easier to work with.

The practical rule is simple: author with JSON5 when comments help, but convert to strict JSON before handing the data to tools that only understand plain JSON. If you keep that boundary clear, JSON5-compatible formatters can improve readability without breaking the rest of your pipeline.