JSON整形ツール

このフォーマッターが受け付けるもの

パーサーはRFC 8259に厳密に従っており、多くの人が思っているより厳格です。キーはダブルクォートで囲む必要があります。文字列もダブルクォートで、シングルクォートは使えません。オブジェクトや配列の最後の要素の後ろにカンマは置けず、コメント構文は一切なく、NaN、Infinity、undefinedもありません。数値は16進数で書けず、先頭に+を付けられず、整数部の先頭にゼロを置くこともできません。

この厳しさは杓子定規ではなく意図的なものです。受け取る側のあらゆるJSONパーサーが適用するのが、まさにこの基準だからです。ここで整形できるドキュメントは、Python、Go、Rust、PostgreSQLでも解析できます。寛容なパーサーが意図を推測してくれた場合にしか動かないドキュメントは、後でどこか、たいていは本番環境で失敗します。

入力にコメントや末尾のカンマがあるなら、それはJSONではなく、tsconfig.jsonなどの設定ファイルで使われる緩い派生形式のJSON5やJSONCです。これらは実際に使われている正当な形式であり、有効なJSONにするためにコメントを削除するのは情報を失う編集です。それを理解したうえで行ってください。

エラーの読み方

解析に失敗すると、エンジンが報告する文字位置から算出した行と列がエラーに含まれます。ただしその位置はパーサーが解析をあきらめた場所であり、必ずしも間違えた場所ではありません。閉じ波括弧が足りない場合は、そこまでの内容がすべてまだ有効でありえたため、たいていドキュメントの末尾で報告されます。

失敗の原因のほぼすべてを占めるのは4つです。閉じ括弧の直前にある余分なカンマ、文字列やキーを囲むシングルクォート、JavaScriptのオブジェクトリテラルからコピーした引用符なしのキー、そして文字列値の中にあるエスケープされていないダブルクォートや改行です。報告された列が引用符を指している場合は、その手前の文字列が早く終わってしまった可能性が高いでしょう。

もう1つよくあるのが、途中で切れたドキュメントです。サイズ制限やタイムアウトで途切れたレスポンスは、値の途中で止まるまでは問題なく解析されるため、エラーは手がかりになる場所ではなく最終行に表示されます。途中を探し回る前に、まず入力の末尾を確認しましょう。

整形の往復で変わること

整形ではドキュメントを解析してから再びシリアライズするため、その過程でいくつかの点が正規化されます。どれが変わるのかを知っておく価値があります。

数値はIEEE 754の倍精度浮動小数点数になります。9,007,199,254,740,991を超える整数は精度を失います。64ビットのデータベースID、Twitter方式のSnowflake ID、ナノ秒のタイムスタンプはすべてこの境界を超えるため、これは重要な問題です。9223372036854775807というIDは9223372036854776000になって返ってきます。これらをそのまま保ちたい場合は、ペイロード内で文字列として扱ってください。末尾のゼロも消え、1.0は1に、1e3は1000に整形されます。

解析の段階でオブジェクトを構築するため、重複したキーは1つにまとめられ、最後のものが残ります。それ以外のキーの順序は保たれますが、JavaScriptのオブジェクトから受け継いだ例外が1つあります。0以上の整数に見えるキーは数値順に並べ替えられ、ほかのキーより前に移動します。コメントと元の空白は、どちらも解析を経て残らないため、当然ながら失われます。

ツリー表示

整形したテキストの上には、折り畳みできるツリーがあります。これは別の用途のためのものです。見慣れないレスポンスの構造、目的のフィールドがどこにあり、どれほど深く入れ子になっているかを、何千行ものインデントされたテキストをスクロールせずに把握できます。関心のない配列を折り畳めば、構造が1画面で読めるようになります。

コピーボタンでコピーされるのは常に整形済みのテキストなので、ツリーで探索しても、エディタに貼り戻す内容が変わることはありません。

JSONの出自と、表現できるもの

JSONは2000年代初頭にDouglas Crockfordによって、JavaScriptのオブジェクトリテラル構文のサブセットとして定められました。ブラウザーがすでに解析できること、そしてXMLは多くのWeb APIが必要とする以上に重いという観察が出発点でした。RFC 4627として標準化され、のちにRFC 8259とECMA-404がそれを引き継ぎました。文法が1ページに収まるという事実が、JSONが広く普及した理由のほとんどを説明しています。

データモデルは意図的に小さく作られています。オブジェクト、配列、文字列、数値、真偽値、そしてnull。それだけです。日付型はなく、バイナリ型もなく、整数と浮動小数点数の区別もなく、コメントもなく、ドキュメントのある部分から別の部分を参照する手段もありません。

JSONの扱いにくい点はすべて、この一覧から導かれます。日付は型ではなく取り決めにするしかなく、バイナリはテキストに符号化するしかなく、大きな整数は数値が通常doubleとして解析される形式にとっては負担になり、コメントを必要とする設定ファイルは方言か、まったく別の形式を使うしかありません。

日付、金額、そして大きな数値

日付については、UTCのISO 8601、たとえば2026-03-14T09:30:00Zという形式が定着した取り決めです。辞書順でそのままソートでき、曖昧さがなく、どの言語でも解析できます。代替案は面倒を招きます。Unixタイムスタンプは秒とミリ秒の区別を失いますし、03/14/2026のようなローカライズされた文字列は、それを書いた国の外では意味が定まりません。

金額はJSONの数値にすべきではありません。パーサーは倍精度浮動小数点数を使ってよいことになっているので、0.1足す0.2の問題がペイロードと一緒にやってきますし、丸めの挙動も言語ごとに異なります。19.99ポンドを1999と表す整数の補助単位を使い、通貨は別のフィールドに置く。これが、どんな利用側でも生き残る表現です。

大きな識別子は同じ問題がより鋭い形で現れます。2^53を超える値はdoubleに解析された時点で精度を失い、これには64ビットのデータベースIDやsnowflake形式の識別子が含まれます。したがって、それらはペイロードの中では文字列であるべきです。これは仮定の話ではありません。いくつかの大手APIがidとid_strの両方のフィールドを返しているのは、まさにこのためです。

メモリに載せきれないほど大きなファイル

ドキュメント全体をオブジェクトとして構築するパーサーは、ファイルサイズの数倍のメモリを必要とします。そのため、空きが数ギガバイトあるマシンでも、500 MBのエクスポートでプロセスが息切れすることがあります。これを避ける方法は2つあります。

1つ目は改行区切りのJSONです。各行が1つの完全なドキュメントで、ファイル全体としては正しいJSONではありません。自然にストリーム処理でき、追記のコストも低く、ほとんどのログ基盤や一括エクスポート形式が採用している形です。2つ目はストリーミングパーサーで、Pythonのijsonや他言語のSAX形式のリーダーがこれにあたります。ファイルをたどりながらイベントを発行し、ツリー全体を実体化することはありません。

コマンドラインでは、jqがそのどちらも扱えますし、それ自体を学ぶ価値のあるツールです。jq '.items[] | {id, name}' big.jsonとすれば、ドキュメントをエディターに読み込むことなく必要な射影だけを取り出せます。--streamフラグは、jqの既定モードでさえメモリを使いすぎるような場合をカバーします。

JSONペイロードのセキュリティ面

JSONの解析そのものは、現代のどの言語でも安全です。リスクはその後に何をするかに潜んでいます。最もよく知られているのがprototype pollutionです。JavaScriptでは、攻撃者が制御できるJSONをフィルターなしにオブジェクトへマージすると、__proto__が設定され、プロセス内のあらゆるオブジェクトの挙動が変わってしまいます。ディープマージ系のユーティリティはこのバグを何度も出荷してきました。防御策は、そうしたキーを明示的に拒否するか、プロトタイプを持たないオブジェクトを使うことです。

JSONを決して評価しないでください。JSON.parseが存在しなかった時代には、evalで解析するのは実際に行われていた手法でしたが、これは届いたものを何でも実行してしまいます。今日、データに対してevalを使っているものは、好みの問題ではなく指摘事項です。

もう少し小さな話も2つ、知っておく価値があります。ブラウザーが実行してしまうContent-TypeでJSON配列を配信することは、かつてのJSON hijacking攻撃の土台でした。一部のAPIがいまもレスポンスの先頭にループを壊す行を付けているのはそのためです。そしてキーの重複は文法上は合法ですが、パーサーによって扱いが異なります。これは、アプリケーションが最終的に読む値とは別の値をバリデーターの前に通してしまう手口として使われてきました。

方言と、それを使うべき場面

JSON5はコメント、末尾のカンマ、引用符なしのキー、シングルクォート文字列を追加します。JSONCはより小さな派生で、Visual Studio Codeが設定ファイルやtsconfig.jsonに使っているもの、本質的には「JSONにコメントを足したもの」です。どちらもJSONではなく、専用のパッケージなしに標準ライブラリで解析することはできません。

重要な区別は、読み手が誰かということです。人間が保守するファイルはコメントから計り知れない恩恵を受けるので、JSON5、JSONC、YAML、TOMLはいずれも妥当な選択肢です。一方、ネットワークを越えるペイロードはプレーンなJSONであるべきです。受け取る側がどの言語のどのライブラリバージョンかは分からず、方言を使うことは相互運用性の保証を依存関係に変えてしまうからです。

設定ファイルを厳格なパーサーに貼り付けて失敗するとき、それは多くの場合、ファイルが壊れているのではなく方言であることを意味します。パーサーを通すためにコメントを削るのは、誰かが書いたドキュメントを失う編集なので、必ずコピーに対して行ってください。