TOML Comments and JSON Conversion

Like YAML, TOML supports comments. Like JSON, JSON has no comment syntax at all. This fundamental difference means that converting TOML to JSON always loses comments, which is one of the main reasons teams prefer TOML for configuration files.

TOML with comments:

# Application settings
[app]
name = "my-service"       # Display name in the dashboard
version = "1.0.0"         # Follows semver

# Server configuration
[server]
host = "0.0.0.0"          # Bind to all interfaces
port = 8080               # Default HTTP port
# port = 443              # Uncomment for HTTPS

# Database connection
[database]
url = "postgres://localhost/mydb"
# WARNING: Change this password in production!
pool_size = 10             # Max concurrent connections

After conversion to JSON, all comments are removed:

{
  "app": {
    "name": "my-service",
    "version": "1.0.0"
  },
  "server": {
    "host": "0.0.0.0",
    "port": 8080
  },
  "database": {
    "url": "postgres://localhost/mydb",
    "pool_size": 10
  }
}

This is irreversible. The comments, including the important WARNING about the database password, are permanently lost. Converting the JSON back to TOML produces valid TOML but without any documentation.

TOML comment syntax:

# Full-line comment
key = "value"  # Inline comment (after the value)

# Comments can appear:
# - On their own line
# - After a value on the same line
# - NOT inside strings (# inside quotes is literal)

message = "Use # for comments"  # This is a comment; the # in the string is literal

Strategies for preserving documentation:

1. Keep TOML as the source of truth. Generate JSON from TOML when needed, but always edit the TOML file. This preserves comments for human readers.
2. Use a description field. Add documentation as data: description = "Max concurrent database connections". This survives conversion but adds data to the structure.
3. JSON Schema. Define a JSON Schema with description fields that document each configuration key. This approach separates documentation from data.
4. Commented-out configuration. In TOML, developers commonly comment out alternative values. This pattern has no JSON equivalent and is lost in conversion.

Comparison with other formats:

• YAML: supports # comments (also lost when converting to JSON)
• JSON: no comments (JSONC is non-standard)
• TOML: supports # comments (lost when converting to JSON)

TOML comments are one of the strongest arguments for using TOML over JSON for human-edited configuration files.