JSONにコメントは書ける？できない理由と3つの回避策

「JSONにコメントを書きたい」「JSONの一部をコメントアウトしたい」と思って // や/* ... */ を追加しても、標準JSONではエラーになります。この記事では、JSONコメントアウトが できない理由と、JSONC・JSON5、ダミーキー、YAMLを使う3つの現実的な回避策を用途別に整理します。

Standard JSON does not support comments: both // and /* ... */cause parse errors. This guide explains why comments were deliberately excluded and compares JSON with Comments (JSONC), JSON5, a _comment property, and YAML.

結論: 標準JSONではコメントアウトできない

標準のJSON（RFC 8259）の文法にはコメントがありません。1行コメント // も、複数行コメント/* ... */ もJSONコメントアウトの書き方としては無効です。当サイトのJSON Formatterでもコメントの位置でパースエラーになります。

{
  // 開発環境のAPI URL
  "apiUrl": "https://api.example.com",
  /* 一時的に無効化したい設定 */
  "debug": true
}

VS Codeで色が付いて見えても有効な標準JSONになったわけではありません。APIやライブラリなどの厳密な JSONパーサーに渡すと失敗するため、コメントを消すか、対応する別形式を選ぶ必要があります。

なぜJSONにはコメントが無いのか

JSONの考案者Douglas Crockfordによると、初期のJSONにはコメント機能がありました。しかし、コメントを 人間向けの説明ではなく、パーサーへの指令や処理用メタデータとして埋め込む人が現れました。 相互運用しやすい単純なデータ交換形式という目的が崩れるため、コメントは意図的に削除されました。

実装漏れではなく、コメント内の非標準な指令へ依存する実装を防ぐための設計判断です。

回避策1: JSONCまたはJSON5を使う

ツールを制御できる設定ファイルなら、JSON with Comments（JSONC）やJSON5が便利です。 JSONCは // と /* ... */ を許容します。VS Codeの settings.json やtsconfig.json など、コメント付きJSONとして扱われる代表的な設定で使われます。 JSON5はコメントに加え、末尾カンマや引用符なしのキーなども許容します。

{
  // 保存時にフォーマットする
  "editor.formatOnSave": true,
  /* ファイルごとの設定 */
  "files.trimTrailingWhitespace": true
}

JSONCやJSON5はRFC 8259準拠のJSONではありません。対応を確認し、APIには標準JSONへ変換して送信してください。

VS Codeでjsonc言語モードとして扱う

画面右下の言語モード「JSON」をクリックし、JSON with Commentsを選択します。 拡張子を .jsonc にするか、特定のファイル名をJSONCへ関連付けることもできます。

{
  "files.associations": {
    "my-config.json": "jsonc"
  }
}

この設定はエディターの検証を変えるだけで、外部のJSONパーサーをJSONC対応にはしません。

回避策2: コメント専用のダミーキーを追加する

標準JSONを維持し、受け手が未知のプロパティを無視できるなら、_comment のような説明専用キーを 追加できます。文字列なので通常のJSONパーサーで処理できます。

{
  "_comment": "本番ではdebugをfalseにする",
  "debug": true,
  "database": {
    "_comment": "接続先は環境変数で上書きする",
    "host": "localhost"
  }
}

複数の説明には _comment_debug のような別名を使います。JSON Schemaで追加プロパティが禁止される場合や、 APIが未知のキーを拒否する場合には使えません。

回避策3: YAMLに変換してコメントを書く

人が編集する設定ファイルでは、# でコメントを書けるYAMLも有力です。JSONデータは当サイトのJSON to YAML ConverterでYAMLへ変換できます。

# 開発環境の設定
apiUrl: https://api.example.com

# 本番では false
debug: true

YAMLは説明の多い設定に向きますが、インデントや型の解釈に注意し、APIへ渡す場合は標準JSONへ変換してください。

場面別: JSONでコメントを使いたいときの早見表

English summary

RFC 8259 JSON has no comment syntax, so // and /* ... */ produce parse errors. Comments were deliberately removed after people used them for parsing directives. Use JSONC or JSON5 only when the consumer supports them. A _comment property can work if unknown fields are allowed, while YAML is often better for human-maintained configuration. Keep API payloads and logs as standard JSON.

関連ツール / Related tools

関連ガイド / Related guides