JSONのコメントについての理解

Key Takeaways

JSONは、純粋なデータ交換を目的とした設計のため、ネイティブのコメント機能がありません。
開発者は、_commentフィールドやプリプロセッサ（例：JSONC）などの回避策を使用します。
設定のユースケースでは、コメントをサポートするYAMLなどの形式を検討してください。

JavaScript Object Notation（JSON）は、サーバーとWebアプリケーション間のデータ交換に最も広く使用されているデータ形式の1つです。軽量で読みやすく、言語に依存しません。ただし、最も一般的な混乱点の1つは、特にXMLのような形式やJavaScriptのようなプログラミング言語に慣れている開発者にとって、JSONでコメントのサポートがないことです。

JSONがコメントをサポートしない理由

JSONは元々、Douglas Crockfordによってシンプルさとデータ交換を念頭に置いて仕様されました。公式JSON仕様（RFC 8259）によれば、コメントはJSONでは許可されていません。その理由は、JSONが純粋なデータ形式であることを意図しているためです。コメントを含めると、パーサー間で相互運用性の問題が発生する可能性があります。

Douglas Crockford自身は、開発者がJSONをコメントが非データコンテンツの保存に使用される可能性のある構成言語として悪用するのを防ぐために、意図的にコメントサポートを削除したと述べています。

回避策と代替案

JSONは//や/* */のような従来のコメントを許可していませんが、開発者はコメントが必要な場合に創造的な（ただし非標準の）回避策を考え出しました。

1. コメント用の特別なフィールドを使用する

カスタムキー（_commentなど）を使用してコメントをシミュレートできます。

{
  "name": "ChatGPT",
  "_comment": "これはnameフィールドに関するコメントです",
  "language": "English"
}

長所:

人間が読めるメモを許可します。
JSONパーサーを壊しません。

短所:

予期していないアプリケーションと干渉する可能性のある追加フィールドを追加します。
不必要にデータを肥大化させる可能性があります。

2. 解析前にコメントを削除する

一部の開発ツールまたはビルドパイプラインでは、コメント付きのJSONファイルが許可され、解析前にコメントを削除します。たとえば、json5、comment-json、または**JSONC（コメント付きJSON）**などのツールを使用すると、ファイルにコメントを記述できますが、クリーンなJSONを出力できます。

// これはコメントです
{
  "enabled": true
}

ただし、解析環境がこのプリプロセスステップをサポートしていることを確認する必要があります。

コメントが必要になる場合

構成ファイル：VSCodeやTypeScriptなどのプロジェクトでは、コメントを含めるために設定ファイル（settings.json、tsconfig.json）にJSONC（コメント付きJSON）を使用します。
ドキュメントの目的：例やAPIスキーマを共有する場合、一時的なコメントは構造を明確にすることができます。

ベストプラクティス

本番環境のJSONファイルでコメントに依存することを避けてください。
コメントが必要な場合は、プリプロセスツールを使用するか、メタデータを個別のドキュメントに含めてください。
構成ファイルの場合は、YAMLまたはTOMLのように、コメントをネイティブにサポートする形式を使用することを検討してください。

結論

JSONのコメントに対する厳格な姿勢は、最初は制限があるように見えるかもしれませんが、データ交換形式としての目的に合致しています。回避策は存在しますが、互換性と明瞭さを維持するために慎重に使用する必要があります。コメントが不可欠な場合は、JSONCをサポートするツールを採用するか、より柔軟な形式を選択することが最良の解決策となる場合があります。