JSONファイルとは

JSON はプレーンテキスト形式です。どのエディターでも開けます。 プログラム間のデータ受け渡しとウェブのために使われます。

拡張子は .json、正式名称は JavaScript Object Notation です。ただしどちらも、そのファイルが中に何を持てるかほどには多くを語りません。このページの残りは、その中身についての話です。

2001 年までさかのぼります。 仕様は RFC 8259 です。

古さが役に立つのは、ごく実務的な理由からです。形式が古いほど、それを覚える時間が多くのプログラムに与えられてきたということだからです。

仕様書がそのまま公開されているので、中身を推し量るのではなく文書を読んで実装できます。この形式が数多くのプログラムに載っているのはそのためであり、20 年前に書かれたファイルが今も開けるのもそのためです。ただし「仕様が公開されている」ことと「使用料が要らない」ことは別の話です。中でコーデックを包んでいる形式では、特許のライセンスは仕様書が答えていない別の問題として残ります。

JSON ファイルは中身をそのまま保存します。保存し直しても何も変わらないので、開いて、直して、また保存する——それを何度繰り返しても劣化は積み上がりません。これが、渡すための形式ではなく作業のための形式である理由です。

JSON ファイルにはコメントを書く方法がありません。説明にあたるものはすべてファイルの外に置くことになります。人が手で面倒を見る用途にこれを選ぶ前に、知っておくべきことです。

Visual Studio Code、jq、Postmanが読めますし、同じ種類のプログラムならたいてい読めます。

ファイルが開かないとき、形式が悪いことはめったにありません。たいていはプログラムのほうが形式より古いのです。もっと古い形式に変換してしまうのが確実な逃げ道で、このサイトの残りの部分はそのためにあります。

これは今のブラウザーならどれでも読めます。

ですからページに置くのも、メッセージに添えて送るのも、安心してできます。相手が何をインストールしているかを考える必要がありません。

JSON は、開いて手を入れるために作られています。作業が続いているあいだはこの形式でファイルを持ち、完成したものが必要になるたびに、ここから書き出してください。

JSON の文書はオブジェクト、配列、文字列、数値、真偽値、null の組み合わせで作られます。語彙はこれだけで、この短さこそがこの形式が広まった理由です。どのプログラミング言語もすでにこの六つをすべて持っているため、文書を読むということは、関数を一つ呼んで、対応付けの必要がないネイティブな値を受け取るだけの作業になります。

仕様書は数ページに収まります。設計されたというより記述されたもので、Douglas Crockford は JavaScript がすでに持っていたオブジェクトリテラルの構文を、すでにうまく機能していたとおりに書き留めました。巧妙というより当たり前に感じられるのはそのためです。

JSON には意図的にコメントがなく、これがこの形式に対する最大の不満です。コメントを許すと解析用の指示まで招いてしまう、という考え方に基づくもので、その結果、JSON は通信形式としては優れていても、設定言語としてはあまり向かないものになっています。

出回っている対処法は三つあります。アンダースコア付きの名前を持つキーにコメントを書く方法は、どのパーサーも通しますが、どのスキーマ検証も拒否します。JSON5 や JSONC はコメントと末尾のカンマを許しますが、これらは JSON ではありません。Visual Studio Code の設定ファイルは JSONC で、厳密なツールで編集するとエラーになるのはこのためです。そして正直な答えは、人が手で保守する設定には TOML や YAML を使うことです。

JSON は整数と浮動小数点数を区別しません。ほとんどのパーサーはすべての数値を倍精度浮動小数点として読み込み、それが整数を正確に表せるのはおよそ九千兆までです。

それを超えると、値は静かに変わってしまいます。64 ビットのデータベース識別子、Twitter 式の snowflake ID、最小単位で表された大きな金額。どれも送られた値とは違う数値になって戻ってくることがあり、どこにもエラーは出ません。対処法はそうした値を文字列として送ることで、まともな API はどれもそうしています。連携先が本当にそうしているかは、想定するのではなく確認する価値があります。

重複するキーは禁止されていません。パーサーによって扱いが違い、最後のものを残すものが多く、最初のものを残すものもあり、エラーにするものもわずかにあります。どちらかの挙動に頼った文書は、JSON にではなく特定の実装に頼っていることになります。

キーの順序も保たれる保証がないため、オブジェクトを順序付きの構造として扱うのは間違いです。順序が重要なら配列を使ってください。日付という型もありません。共通の慣習は ISO 8601 形式の文字列で、どのパーサーも、あとで解釈する必要のある文字列を渡してくるだけです。

JSON は UTF-8 です。仕様書はシステム間でやり取りされるあらゆる JSON についてそう定めていて、実務上の帰結として、バイトオーダーマークは許されません。ファイルの先頭にある三つの目に見えないバイトが解析エラーを引き起こし、そのエラーメッセージはたいてい原因ではなく最初の文字を非難します。

エディター上では完璧に見える JSON ファイルが解析に失敗する場合、まずこれを疑ってください。「BOM なしの UTF-8」という設定が必要で、これはこのサイトの他のテキスト形式にも共通する助言ですが、JSON の場合はちょっとした不快さではなく、本当に致命的になる点が違います。

JSON の文書は解析される前に完結している必要があります。閉じ括弧があって初めて有効になるためで、十ギガバイトのレコードの配列は、最初の一件を取り出すためだけでも全体をメモリーに読み込む必要があります。大きなエクスポートやログのパイプラインにとって、これは致命的です。

NDJSON、別名 JSON Lines はこれを解決します。囲む配列を持たず、各行に一つの完結した JSON オブジェクトを置くだけです。各行は独立して解析できるため、どんな大きさのファイルでも一行ずつストリームで処理でき、最初の一件が届いた瞬間に処理を始められます。データのエクスポート、ログの転送、機械学習のデータセットのほとんどがこれを使っていて、JSON ファイルがギガバイト単位になったときに頼るべき形式です。

JSON Schema は、有効な文書の形を記述する標準的な方法で、二つのシステム間のやり取りにはぜひ使う価値があります。「API が何かおかしいものを返した」という状況を、どのフィールドが原因かを名指しする具体的なエラーに変えてくれます。対応状況は良好ですが、XML の対応する仕組みほど一様ではありません。

日常の作業では、JSON に対応したエディターを使うだけで多くが解決します。足りないカンマや余分なカンマをその場で指摘してくれ、一行の長い文字列として届いた機械生成の JSON も読みやすく整形できます。どちらも数秒の操作で、驚くほどの時間を節約してくれます。