JSON にコメントは書けるか

要点：標準 JSON には決してコメントを入れず、人間だけが編集するローカル設定には JSONC や JSON5 を使い、ファイルがシステムをまたぐなら説明を JSON Schema の description に移し、注釈が増えたら YAML や TOML に切り替えましょう。

書けません。

標準に準拠したパーサーはこれを拒否します。

复制{
  "port": 8080 // ローカル開発専用
}

Chrome は SyntaxError: Unexpected token } を報告します。パーサーは / にぶつかり、それはどの JSON 値も開始できないので、止まったのです。

なぜ仕様は意図的にコメントを除外したのか

RFC 8259 は六つの値を定義します。オブジェクト、配列、数値、文字列、true/false、null。コメントの生成規則はありません。

コメントは早くに提案され、具体的な理由で拒否されました。コメントが合法になると、誰かがそれを指令の運搬に使うのです。条件付きインクルード、テンプレート変数。そしてすべてのパーサーが独自の方言を育てます。相互運用性は最初のホップで壊れます。JSON は意図的にデータ専用で、中に実行可能なものを何も持たないのです。

注記を残す四つの方法

1. 上位集合を使う。 JSON5 と JSONC はどちらのコメントスタイルも受け入れます。VS Code の settings.json と tsconfig.json は JSONC です。 コストは現実です。JSON.parse は依然として拒否し、API、ログパイプライン、メッセージキューは通常標準 JSON しか受け付けません。コメントは静かに落とされるか、下流のどこかで例外を投げます。

2. 注記をデータに入れる。

复制{
  "_comment": "ポートは運用が割り当て。変更しないこと",
  "port": 8080
}

どこでも動きますが、モデルを汚します。すべての消費者がどのキーを無視するかを知らなければならず、型定義に本当のデータではないフィールドが増えます。

3. Schema の description を使う。 description は人間とツールのためにあります。バリデータはそれを表面化し、エディタはホバーで表示し、ペイロードには決して入りません。互換性を壊さず長期的な保守に耐える唯一の選択肢です。

4. ファイル形式を変える。 ファイルが手で編集されるために存在するなら、YAML や TOML はコメントをネイティブにサポートします。ここで JSON と戦うのは無駄な労力です。

選択

FAQ

_comment フィールドがモデルを汚すのはなぜですか？

データの一部になるからです。すべての消費者がどのキーを無視するかを知らなければならず、型定義に本当の業務データではないフィールドが増えます。

説明は JSON Schema の description に置くべきですか？

はい。description はペイロードの外に留まり、バリデータが表面化し、エディタがホバーで表示するので、互換性を壊さず長期的な保守に耐える唯一の選択肢です。

JSONC や JSON5 は JSON.parse でパースできますか？

いいえ。JSON.parse は依然コメントを拒否し、API、ログパイプライン、メッセージキューは通常標準 JSON しか受け付けないので、コメントは落とされるか下流で例外を投げます。

ツール

• JSON5 パーサー — コメント付き設定を貼り、解決後の構造を確認
• JSON フォーマッタとバリデータ — 不正な JSON を行と列付きで報告し、問題のコメントが一目で分かる

さらに読む

• JSON5 と JSONC：コメント付き JSON
• JSON パースエラーのトラブルシューティング
• 設定、フィクスチャ、ローカルデータの管理