JSON Heroは、JSONを「読む」から「歩く」に変える

はじめに

APIのレスポンスをデバッグしているとき、ターミナルに吐き出された巨大なJSONを目で追って、目当てのキーを探した経験はありませんか。jqでフィルタをかけても、ネストが深いJSONだと結局どこに何があるのか把握しづらく、エディタに貼り付けて折りたたみながら探す羽目になることも多いはずです。

JSON Heroは、そんな「JSONを読む」という作業を、macOSのFinderのように階層をクリックして歩く体験に変えてくれるツールです。Trigger.devのチームが開発しているオープンソースのJSONエクスプローラーで、キーや値をたどるたびに関連する情報がプレビューされるため、構造を頭の中で組み立て直す手間がぐっと減ります。

JSON Heroとは

JSON Heroは、JSONファイルやAPIレスポンスをブラウザ上で見やすく表示するためのWebアプリケーションです。jsonhero.ioにアクセスすればすぐに使い始められるホスティング版があり、ソースコードはMITライセンスで公開されているため自前でホストすることもできます。Remix製のWebアプリとして実装されており、npmパッケージとして自分のコードに組み込む種類のライブラリではなく、「開いて使うツール」として提供されている点が特徴です。

主な特徴

Column View（列表示） - macOSのFinderに似た列形式のUIでJSONの階層をたどれます。Option（WindowsはAlt）キーを押しながら親階層に移動すると、選択していた子要素を保持したまま兄弟要素を比較でき、配列内の値の違いを素早く確認できます
Tree ViewとEditor View - 従来型のツリー表示と、値のプレビューを保ったままのエディタ表示も切り替えられます。表示形式は用途に応じて選べます
値の自動推論とプレビュー - 文字列の中身を自動で判定し、日時・URL・画像URL・カラーコード・ツイートURLなどをその場でプレビュー表示します
JSON Schemaの自動生成 - 開いたJSONから対応するJSON Schemaを推論して表示するため、そのままバリデーション用のスキーマとして流用できます
キーと値の全文検索 - フォーマット済みの値（例えば日時文字列の「Dec」で12月のデータを検索するなど）にも対応した高速な検索パネルを備えています
共有しやすいURL - 開いたJSONにはパス付きのURLが発行され、特定のキーを指し示した状態でそのまま同僚に共有できます

インストール（利用開始方法）

JSON Heroはコマンドラインツールではないため、npmパッケージとしてインストールする使い方は基本的にありません。用途に応じて次のいずれかで使い始めます。

# ブラウザからそのまま使う場合はインストール不要
# https://jsonhero.io を開くだけ

# セルフホストする場合はリポジトリをクローンして起動
git clone https://github.com/triggerdotdev/jsonhero-web.git
cd jsonhero-web
npm install

# .env に SESSION_SECRET を設定してからビルド・起動
npm run build
npm start

VS Codeから直接JSONを開きたい場合は、JSON Hero拡張機能をVS Code Marketplaceからインストールします。

基本的な使い方

一番手軽な使い方は、jsonhero.ioにJSONファイルをドラッグ&ドロップするか、JSONテキストをそのまま貼り付けることです。JSONのURLを直接渡すこともでき、次のようにアクセスするだけでそのAPIレスポンスをJSON Heroで開けます。

https://jsonhero.io/new?url=https://jsonplaceholder.typicode.com/todos/1

開くと自動的にColumn Viewが表示され、キーをクリックしていくたびに右側のパネルに値の型やプレビュー、そのキーが持つJSON Schema上の制約が表示されます。文字列が日時形式であれば人間が読める日付として、URLであればリンクカードとして、それぞれ自動でプレビューされるのがJSON Heroらしいところです。

実践的なユースケース

1. APIレスポンスのURLを渡すだけで確認する

デバッグ中に「このエンドポイントのレスポンス、ちゃんと見たい」というとき、いちいちファイルに保存しなくても、URLをJSON Heroのnewエンドポイントに渡すだけで済みます。

https://jsonhero.io/new?url=https://api.example.com/users/42

Base64エンコードしたJSON文字列を直接渡すことも可能です。

https://jsonhero.io/new?j=eyAiZm9vIjogImJhciIgfQ==

チームメンバーに「このAPIのレスポンス構造を見て」と伝えるとき、Slackにこの1行のURLを貼るだけで、相手はColumn Viewで階層をたどりながら確認できます。

2. VS Codeを離れずにJSONファイルを開く

VS Code拡張機能をインストールすると、エディタ上で開いているJSONファイルをコマンドパレットから直接JSON Heroに送れます。設定ファイルやAPIのモックデータなど、頻繁に構造を確認するファイルがある場合、ブラウザとエディタを行き来する手間が減ります。

3. Dockerでセルフホストして社内ネットワークに閉じる

顧客情報を含むJSONなど、外部のホスティング版に貼り付けたくないデータを扱う場合は、リポジトリをクローンしてDockerでセルフホストできます。

docker build -t jsonhero-web .
docker run -p 8787:8787 -e SESSION_SECRET=your-secret jsonhero-web

http://localhost:8787でアクセスできるようになり、社内ネットワークの中だけで完結させられます。

4. 非公式APIでJSONドキュメントを生成してURLを発行する

CIのテスト結果やビルドログのJSONを、後から見返せる形でURL化しておきたい場合は、create.jsonエンドポイントにPOSTしてドキュメントを生成できます。

curl -X POST https://jsonhero.io/api/create.json \
  -H "Content-Type: application/json" \
  -d '{
    "title": "build result #123",
    "content": { "status": "success", "duration": 42 },
    "readOnly": true,
    "ttl": 3600
  }'

レスポンスにはドキュメントのURLが含まれるため、CIのログにそのURLを出力しておけば、あとからクリック一つで結果を見返せます。ttlを指定すれば一定時間後に自動で破棄されるため、機密性の低い一時データの共有に向いています。

まとめ

JSON Heroは、JSONを「テキストとして読む」のではなく「階層を歩いて把握する」ためのツールです。Column Viewによる直感的な階層移動、値の自動プレビュー、JSON Schemaの自動推論といった機能が組み合わさり、複雑なAPIレスポンスや設定ファイルの構造把握を大きく楽にしてくれます。ホスティング版でまず試してみて、機密データを扱うようであればセルフホストに切り替える、という段階的な導入がしやすい点も魅力です。次にAPIレスポンスの構造を確認する場面があれば、jqやエディタの折りたたみに頼る前に、一度JSON Heroに通してみてください。