JSONにコメントを書けなくて困っていませんか？
設定ファイルやデータを扱っているときに、
「ここに補足説明を残しておきたいのに、JSONってコメントが書けないんだよな…」
と悩んだことはありませんか？
実は JSONの仕様そのものにはコメントが存在しません。
そのため、単純に // や /* */ を書くとエラーになってしまいます。
しかし、工夫次第で「実質コメント」として扱える方法はいくつか存在します。
この記事では、実務でよく使われる4つの方法を紹介し、それぞれのメリット・デメリット、使いどころを解説します。
この記事を読むと分かること
- JSONに公式のコメントがない理由
- 代替的にコメントを入れる4つの具体的な手法
- VS Codeなど一部環境で使えるJSONC について
- 本番環境で安全に使うための注意点とベストプラクティス
「とりあえずコメントを残したいだけ」から「長期運用で困らない方法を知りたい」まで、あなたの状況に合わせて選べるようになります。
JSON
JavaScript Object Notation（JSON）は、これを可能にするデータ交換形式です。 JSONは、人間が読めるテキストであり、軽量で、コーディングが少なくて済み、処理が高速であるため、データ形式として多くの開発者に選ばれています。
https://www.oracle.com/jp/database/what-is-json/#:~:text=JavaScript%20Object%20Notation%EF%BC%88JSON%EF%BC%89%E3%81%AF,%E3%81%AB%E9%81%B8%E3%81%B0%E3%82%8C%E3%81%A6%E3%81%84%E3%81%BE%E3%81%99%E3%80%82
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」とは関係がないものです。
