JSONの仕様上、コメントアウトは標準でサポートされていません。
設定ファイルやデータ構造の定義中に「なぜこの値なのか」をメモ書きできず、不便を感じているエンジニアも多いはずです。
事実、JSONの標準規格（RFC 8259）にはコメントの定義がなく、安易に // や /* */ を記述するとパースエラーを引き起こします。しかし、実務現場では「擬似的なキー」の活用や、「JSONC」「JSON5」といった拡張仕様を用いることで、安全にコメントを残す手法が確立されています。
この記事では、実務でよく使われる4つの方法を紹介し、それぞれのメリット・デメリット、使いどころを解説します。
この記事を読むと分かること
「とりあえずコメントを残したいだけ」から「長期運用で困らない方法を知りたい」まで、あなたの状況に合わせて選べるようになります。
1. コメントをデータとして保持する
単純にJSONのルールに乗っ取ったデータの一つとして、コメントを保持するようにします。
こんな感じ。
{
"_comment": "コメントをデータとして保持する",
"id": "hogehoge_id",
"name": "ほげほげ"
}データとして、使用しないことが分かりやすいように、キー名を_(アンダースコア)始まりにするとか、それぞれルールを決めておくと良いかと思います。
以下のように、キー名を空にしちゃうってのも一つの手です。
{
"": "コメントをデータとして保持する",
"id": "hogehoge_id",
"name": "ほげほげ"
}2. 2行以上のコメントも書きたい
はい、そういう時もありますよね。少し癖がありますし、扱いづらさは否めないですが、同様にJSONのデータとして持たせることで実現できます。
こんな感じで配列にしてしまいます。
{
"_comments": [
"1行目のコメント",
"2行目のコメント"
],
"id": "hogehoge_id"
}3. 複数のキーに対して、それぞれにコメント付けたい
要するにJavaScriptであれば、こういうことができます。
// TwitterのIDが入ってる
var id = "hogehoge_id";
// Twitterの名前
var name = "ほげほげ";こんな感じでJSONファイルにも、それぞれの行に対してコメントを付けたい場合はどうするのが良いのでしょう？
こんなやり方があります。
{
"id": "TwitterのIDが入ってる",
"id": "hogehoge_id",
"name": "Twitterの名前",
"name": "ほげほげ"
}JSONでは、キーが重複している場合、前に書いた方は無視されます。(上書きされます）
そのため、上記のような書き方ができます。ただ、可読性が落ちることは否めないですね。
4. JSONCを使う
もし、JSONCを使える環境であれば、これが最もスマートな解決策となります。
JSONCとは
JSONCは、コメントを含めることができるように拡張されたJSONです。JSONCでは、ブロック（/ * * /）および単一行（//）コメントを使用することができます。
Microsoft公式がparserを開発・公開しているため、かなり使いやすくなりました。Visual Studio Code では標準機能としてJSONCを取り扱うことができるようになっています。
書き方
特殊な書き方はないです。単純にJSONでコメントが使えるというだけです。
{
// これはTwitterのidです
"id": "hogehoge_id",
/*
この先は必須ではない
*/
"name": "ほげほげ",
"created": "2020/1/12",
}ちなみに、JSONにコメントが書けるというだけではなく、リストの末尾の要素にカンマ「,」をつけることができるという点も地味ですが、慣れると助かるJSONCを使う利点です。
5. JSON5を使う
JSON5とは？
JSON5 は、JSONの拡張仕様のひとつです。
従来のJSONよりも 柔軟で読みやすい記法 を可能にし、その一環として コメントをサポート しています。
つまり、JavaScriptでおなじみの
// これはコメントです
{
// サーバーの接続先
host: "localhost",
port: 8080, // デフォルトポート
}のように書けます。
（JSON5ファイルは拡張子として .json5 を用いるのが一般的です）
メリット
- 素直にコメントが書ける
//や/* */がそのまま利用可能。 - 記述が簡潔になる
文字列のクォーテーション省略、末尾カンマの許容など、JSONに比べて柔軟。 - 既存ツールが充実
Node.jsならjson5パッケージ、Pythonならjson5ライブラリを使えばすぐに扱える。
デメリット
- 公式仕様ではない
JSON5はあくまでコミュニティ仕様であり、標準JSONライブラリでは扱えません。 - 互換性の問題
JSON5ファイルをそのまま「JSON」として読み込むとエラーになります。 - 外部ツール依存
本番環境や外部サービスに渡す場合は、変換やコメント削除が必要です。
使いどころ
- 開発時の設定ファイル
プロジェクト固有の設定やオプションを残す際に便利。 - チームでの共有メモ
コメント付きで書けるので、メンバー全員が理解しやすい。
ただし、本番で外部システムに渡すデータは標準JSONに変換する のが鉄則です。
まとめ
JSONファイルにコメントを書く方法をいくつかご紹介しました。私は、直近の個人開発では一番上の"_comment"のパターンを使っています。
どれを使うかは好みの問題ですが、チーム開発で使う場合には、チーム内の統一規格としてドキュメント化しておくのが良いでしょう。
余談:「json-c」は別物
余談ですが、「json-c」というプロジェクトがありますが、単なるC言語でJSONを利用するためのライブラリであり、今回紹介した「JSONC」とは関係がないものです。
