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でコメントを使いたいときの早見表

JSONCとJSON5の違い

「JSONC」と「JSON5」はどちらもコメントを許容しますが、許容範囲は同じではありません。 VS Codeのtsconfig.json等で使われるJSONCはコメントとトレイリングカンマ程度の 拡張にとどまりますが、JSON5(json5.org)はより広い範囲の緩和を仕様化しています。

tsconfig.jsonのような「見た目はJSON、コメントだけ許容」という程度ならJSONC、 設定ファイルとしてより人が書きやすい構文がほしいならJSON5、という使い分けになります。

実際にパースするには専用ライブラリが必要

VS Code上でエラーが出ないからといって、JSON.parse()がJSONCやJSON5に対応した わけではありません。標準のJSON.parse()はコメント・末尾カンマを含む文字列を渡すと 必ずSyntaxErrorになります。実行時に読み込むには専用のパーサーライブラリが必要です。

// 標準JSON.parseはコメント入りJSONCを解析できない(SyntaxErrorになる)
JSON.parse(fs.readFileSync("settings.json", "utf-8"));

// JSONC用のパーサーを使う(VS Code内部でも使われているパッケージ)
import { parse } from "jsonc-parser";
const config = parse(fs.readFileSync("settings.json", "utf-8"));

// JSON5用のパーサーを使う
import JSON5 from "json5";
const config5 = JSON5.parse(fs.readFileSync("config.json5", "utf-8"));

設定ファイルとしてJSONC/JSON5を採用する場合は、読み込み側のコードも標準のJSON.parseから専用パーサーへ差し替える必要がある点を忘れないでください。

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.

よくある質問 / FAQ

JSONにコメントは書けますか?

標準のJSON(RFC 8259)の文法にコメントはありません。1行コメントも複数行コメントも無効で、パースエラーになります。

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

初期のJSONにはありましたが、コメントをパーサーへの指令や処理用メタデータとして埋め込む人が現れたため、相互運用しやすい単純なデータ交換形式という目的を守るために削除されました。

VS Codeでコメント付きJSONを書いてもエラーが出ないのはなぜですか?

言語モードがJSONC(JSON with Comments)になっているためです。これはエディターの検証を変えるだけで、外部のJSONパーサーが受け付けるようになるわけではありません。

標準JSONのままコメントを残す方法はありますか?

_comment のような説明専用のダミーキーを追加する方法があります。値は文字列なので通常のJSONパーサーで処理でき、受け手が未知のプロパティを無視できる場合に使えます。

JSONCとJSON5の違いは何ですか?

JSONCはコメントとトレイリングカンマ程度の拡張にとどまりますが、JSON5はより広い構文拡張を持ちます。どちらも標準の JSON.parse() では読めず、専用ライブラリが必要です。

関連ツール / Related tools

関連ガイド / Related guides