JSON5 and Commented JSON: When Trailing Commas and Comments Are Safe

Standard JSON is strict by design. It is excellent for APIs, logs, and machine-to-machine data exchange, but it does not allow comments, trailing commas, single-quoted strings, or unquoted property names.

That strictness surprises many developers because real configuration files often look like this:

{
  // Development API endpoint
  apiBaseUrl: 'https://api.example.com',
  retryCount: 3,
  features: {
    betaSearch: true,
  },
}

This is not valid JSON. It is closer to JSON5 or JSONC-style configuration. The difference matters when you copy a config snippet into an API request, a database field, an environment variable, or a tool that expects plain JSON.

What JSON5 Adds

JSON5 is a relaxed JSON syntax intended for human-written configuration. Common conveniences include:

• Line comments and block comments.
• Trailing commas in objects and arrays.
• Single-quoted strings.
• Unquoted object keys when they are valid identifiers.
• More flexible number formats.

These features make config files easier to edit and review. They are useful in build tools, editor settings, local scripts, and internal configuration where humans maintain the file directly.

What JSON Does Not Allow

Plain JSON keeps a smaller rule set so parsers can behave consistently across languages. In strict JSON:

• Object keys must use double quotes.
• Strings must use double quotes.
• Comments are not allowed.
• Trailing commas are not allowed.
• The top-level value must follow the JSON grammar exactly.

For example, this will fail in JSON.parse():

{
  "name": "MyToolster",
  "enabled": true,
}

The final comma after true is enough to make the payload invalid.

JSON5 vs JSONC

JSON5 and JSONC are related ideas, but they are not the same contract.

JSON5 is a published relaxed syntax with features such as single quotes and unquoted keys. JSONC usually means JSON with comments, commonly seen in editor and tool configuration files. Some JSONC parsers allow trailing commas, while others may reject them depending on the tool.

That means the safest question is not "does this look readable?" The safer question is "which parser will read this exact file?"

The names are sometimes used loosely in documentation, so always check the actual parser. A tool may say "JSON with comments" but still reject single quotes or trailing commas.

When Commented JSON Is Safe

Commented JSON is reasonable when the consumer explicitly supports it. Examples include some editor settings, local tool config files, and project-specific parsers that document JSON5 or JSONC support.

It is risky when the same text is sent to:

• A REST API request body.
• A webhook payload.
• A database JSON column that validates strict JSON.
• A browser call to JSON.parse().
• A command-line tool that expects RFC-style JSON.

In those cases, remove comments and relaxed syntax before sending the data.

Configuration files vs data exchange

The practical divide is simple: configuration files are often written by humans, while API payloads are usually exchanged by machines.

Human-maintained config benefits from comments:

{
  // Enable only in staging until the rollout is complete.
  enableNewCheckout: true,
  retryDelayMs: 250,
}

That comment helps a teammate understand why the setting exists. But if the same object becomes an API payload, the receiving service may use a strict JSON parser:

{
  "enableNewCheckout": true,
  "retryDelayMs": 250
}

For production APIs, strict JSON is safer because every language and platform can parse it consistently. For local configuration, JSON5 or JSONC can be acceptable if the tool documents support for it.

Common files that look like JSON

These file names often cause confusion:

• package.json is strict JSON. Do not add comments.
• tsconfig.json is commonly parsed as JSONC by TypeScript tooling.
• .vscode/settings.json commonly supports comments in VS Code.
• .eslintrc.json may depend on the tool version and loader.
• API request examples in docs should usually be strict JSON.

If you copy from a config file into an API client, normalize the syntax first. If you copy from an API response into a config file, keep it strict unless the config parser explicitly supports comments.

How to Convert JSON5-Style Config to Strict JSON

Use this checklist before pasting relaxed config into an API, database, or production setting:

1. Remove // and /* */ comments.
2. Remove trailing commas from objects and arrays.
3. Change single-quoted strings to double-quoted strings.
4. Quote all object keys.
5. Confirm booleans and null values are lowercase: true, false, null.
6. Format the result with a strict JSON formatter.

For the earlier JSON5-style example, the strict JSON version is:

{
  "apiBaseUrl": "https://api.example.com",
  "retryCount": 3,
  "features": {
    "betaSearch": true
  }
}

Common Error Messages

When relaxed JSON is parsed as strict JSON, the error message often points near the first unsupported character. Typical causes include:

• Unexpected token /: a comment was found.
• Unexpected token }: a trailing comma appeared before a closing brace.
• Unexpected token ': a single-quoted string was used.
• Unexpected token a: an unquoted key such as apiBaseUrl was used.

The message may not say "JSON5 is unsupported." It usually reports the exact token that broke the strict JSON parser.

Safe cleanup workflow

When converting relaxed JSON into strict JSON, avoid global find-and-replace unless the file is tiny and you understand every value. A quote replacement can break apostrophes inside strings, and comment removal can break URLs such as https://example.com if done with a naive regex.

A safer workflow is:

1. Keep the original JSON5 or JSONC file.
2. Paste a copy into a formatter that understands comments.
3. Choose strict JSON output.
4. Validate the result with a strict parser.
5. Compare important values such as URLs, numbers, booleans, and arrays.
6. Use the strict version only for APIs, webhooks, database import, or browser JSON.parse().

This is especially important for feature flags, payment settings, redirect URLs, and deployment configuration, where a small formatting change can change application behavior.

Security and operational notes

Comments in config files can accidentally expose context that should not travel with data. A comment may mention an internal service name, rollout plan, customer name, or temporary workaround. Removing comments before sending a payload is not only about syntax; it also reduces accidental information leakage.

Trailing commas can also hide mistakes in review. In a strict API payload, every item is explicit, and the final item has no comma. That makes diffs slightly noisier, but it keeps payloads predictable across languages.

Practical Workflow

Keep JSON5 or commented JSON in files that are meant for humans, such as local config. Before moving that data into an API request, a database field, or a browser-only JSON.parse() workflow, normalize it to strict JSON.

If you need to check a payload quickly, paste it into the JSON Formatter. For payloads embedded in query parameters, combine it with the URL Encoder. If the JSON was transported as Base64, decode it first with the Base64 Tool, then validate the decoded text as JSON.