JSONPathの使い方: 記号ごとの意味を例で確認

公開ツールJSONPathクエリテスター

目次
  1. APIレスポンスから欲しい値だけを取り出したいときにつまずくこと
  2. ツールを使わず、記号のルールだけで自分で計算する方法
  3. よくつまずくポイント
  4. まとめ
  5. よくある質問

JSONPathのパス式が目的の値を正確に指しているかどうかは、目で見ただけでは確信しにくいものです。$、.、[ ]、[*]、.. といった記号は、決められたルールに従って評価されます。

そのルールさえ分かっていれば、どのパス式がどの値を選ぶのかを手作業でも追跡できます。この記事では、1つのサンプルJSONを使い、各記号が実際に何を選択するのかを1つずつ確認していきます。

まとめ ① $ はJSONドキュメント全体を、.プロパティ や ['プロパティ'] はオブジェクトの特定のキー1つを指します。 ② [数値] は配列のn番目の値(負の数は後ろから数える)を、[*] や .* はその位置にあるすべての値を指します。 ③ .. はすべての階層を再帰的に探し、結果は一致件数にかかわらず常に配列で返ります。

APIレスポンスから欲しい値だけを取り出したいときにつまずくこと

JSONデータを扱っていると、$.data.items[0].name のような形のパス式をドキュメントやサンプルコードでよく見かけます。この式1つで、入れ子になったJSON構造のどこかにある値1つを直接指せる、というのがJSONPathの要点です。

問題は、そのパス式が自分のJSON構造でも同じように動くかどうかです。キー名が違っていたり配列の順序が違っていたりすると、見た目が似ているパス式がまったく別の値を指したり、何も見つけられなかったりします。

大括弧の中に数値を入れるのか * を入れるのか、. の後に * を付けると何が変わるのか、.. は正確にどこまで探すのか — 記号1つの違いで結果が変わるのに、その違いを目だけで予測するのは簡単ではありません。

ツールを使わず、記号のルールだけで自分で計算する方法

JSONPathは実装ごとにサポートする文法の範囲が少しずつ異なります。ここで整理する5つのルールは、以下のサンプルJSONを前提に、文字どおり1つずつ適用すれば結果を手作業でも再現できる範囲です。

{
  "store": {
    "book": [
      { "title": "貧しいチャーリーの年鑑", "price": 22000 },
      { "title": "賢明な投資家", "price": 18500 }
    ],
    "bicycle": { "color": "red", "price": 129000 }
  }
}

ルールは5つです。

  1. $ — ドキュメント全体を指します。パス式が $ だけなら、結果はこのJSON全体が入った配列1つです。
  2. .プロパティ または ['プロパティ'] — オブジェクトからその名前のキーを1つ選択します。$.store.bicycle.color は文字列 "red" 1つを指します。
  3. [数値] — 配列からその順番(0から始まる)の値を1つ選択します。負の数は配列の末尾から数えます。$.store.book[0] は最初の本を、$.store.book[-1] は最後の本を指します。
  4. [*] または .* — その位置にあるすべての値を選択します。$.store.book[*] はbook配列の要素である本のオブジェクト2つをすべて選択します。
  5. .. — 後ろに続く名前を、ドキュメントのすべての階層で探します。$..price はbookの中のprice 2つとbicycleのpriceまで、合計3つを見つけ出します。

$.store.book[*].title が実際にどう評価されるのかを順番に追うと、次のようになります。

  • 1段階 $ → ドキュメント全体1つが対象です。
  • 2段階 .store → storeオブジェクト1つに絞られます。
  • 3段階 .book → book配列1つ(配列そのものが値)に絞られます。
  • 4段階 [*] → book配列の各要素、つまり本のオブジェクト2つに広がります。
  • 5段階 .title → 残った本のオブジェクトそれぞれからtitleキーを取り出し、文字列2つになります。

最終結果は ["貧しいチャーリーの年鑑", "賢明な投資家"] で、一致件数は2件です。この5つの段階をそのまま適用すれば、どんなパス式でも結果を手作業で予測できます。

手作業でたどったこの5つの段階が、自分のJSONとパス式でも正しく計算されるか、無料ツールで確認してみましょう。

JSONPathクエリテスター

JSONとパス式を入力すると、一致した値と件数をその場で表示します。データはブラウザ内だけで処理され、サーバーには送信されません。

よくつまずくポイント

JSONPathを初めて使うと、結果が予想と違って出てくる場面がいくつかあります。以下は、実際にそのパス式を入れたときに起こることです。

入力したパス式実際に起こること
$.store.book[1:3](スライス)エラーにはならず「一致する値がありません」と表示されます。大括弧の中の文字列がスライスとして解釈されず、そのままプロパティ名として扱われますが、bookは配列なので名前では何も見つかりません。
$.store.book[?(@.price>20000)](フィルター式)同じ理由でマッチは0件です。?() のフィルター文法は解釈されず、大括弧の中全体がプロパティ名として扱われます。
$.store.book[10](範囲外のインデックス)エラーにはならずマッチ0件です。配列の長さを超えたインデックスは、静かに結果から外れます。
$.store.book(配列そのものを選択)book配列全体が1つの一致値として包まれて出てきます。つまり結果は、配列を入れた配列の形になります。
$ 単独ドキュメント全体が入った1件だけの配列が結果として出てきます。

フィルター式やスライスが静かに失敗するのは、大括弧の中の内容をインデックスの数値、ワイルドカード(*)、引用符で囲んだ名前 — この3つの形でしか解釈しないためです。

3つの形に当てはまらない内容は、すべて「その名前のキーを探せ」という意味として処理され、そうしたキーは実際に存在しないので結果は空になります。

まとめ

  • $ はドキュメント全体、.プロパティ や ['プロパティ'] はオブジェクトのキー1つを指します。
  • [数値] は配列のインデックス(負の数は後ろから数える)、[*] や .* はその位置にあるすべての値を指します。
  • .. はすべての階層を再帰的に探し、一致する値をすべて集めます。
  • 結果は一致件数にかかわらず常に配列で返り、一致がなければエラーではなく「一致する値がありません」と表示されます。
  • フィルター式 ?() とスライス [1:3] はサポートされておらず、サポート範囲外の文法はエラーではなく静かなマッチ0件として現れます。
JSONPathクエリテスター

JSONとパス式を入力すると、一致した値と件数をその場で表示します。データはブラウザ内だけで処理され、サーバーには送信されません。

よくある質問

結果がなぜいつも配列で返ってくるのですか?

[*] や .. は複数の値を一度に探せるため、一致件数にかかわらず結果を配列に統一して表示しています。$ だけを入力してドキュメント全体を指す場合も、要素1件だけの配列として返ります。

フィルター式 ?() やスライス [1:3] はなぜサポートしていないのですか?

このツールが解釈するのは $、.プロパティ、['プロパティ']、[数値]、[*]・.*、.. の6つの文法だけです。

?() や [1:3] のようにこの範囲を外れた文法を入れると、エラーではなく大括弧の中身をそのままプロパティ名として扱い、マッチ0件として処理します。

入力したJSONはサーバーに送信されますか?

いいえ。JSONのパースもパス式の評価もすべてブラウザの中だけで行われ、入力したデータがサーバーに送信されたり保存されたりすることはありません。

負のインデックスは具体的にどう計算されるのですか?

配列の長さに負のインデックスを足した値が実際の位置になります。たとえば要素が2つある配列で [-1] は 2 + (-1) = 1番目、つまり最後の要素を指します。計算した位置が配列の範囲を外れる場合はマッチ0件になります。

この記事は韓国語の原文をもとに作成しています。 韓国語の原文を読む

関連記事

  1. JWTデコード方法|構造とexp・iatの読み解き方JWTは暗号化ではなくエンコードなので、誰でも中身を読めます。header.payload.signatureの構造とbase64urlデコードの仕組み、exp・iatの秒単位の値を日時に直す方法をまとめました。
  2. JWTの署名を検証して改ざんを確認する方法JWTはheader.payload.signatureの3部分で、payloadは暗号化ではなくエンコードのみです。HMAC-SHA256の署名計算の仕組みと、検証に失敗する2つの原因(鍵の不一致・改ざん)を解説します。
  3. line-clamp CSSの使い方、動かない原因と対処line-clampが効かない原因は、ほとんどがdisplay: -webkit-boxの指定漏れです。1行と複数行の省略で使うプロパティの組み合わせの違いをコードで解説し、行数や幅を変えながらリアルタイムで確認できます。
  4. 箇条書き変換ツールの使い方 — Markdown・HTMLリストに変換行頭の記号や番号を消して、Markdownリスト・HTMLのul/liタグ・任意の記号の箇条書きへ一度に変換する方法と、つまずきやすい点をまとめます。
  5. ローカルストレージとセッションストレージの違いと確認方法ローカルストレージとセッションストレージの保存期間の違い、開発者ツールでの確認方法、QuotaExceededErrorの原因を整理。表形式で操作できるツールも紹介します。
  6. 原稿用紙の枚数計算 文字数÷200で合わない理由文字数を200で割っても原稿用紙の枚数と合わない理由を、20字詰めの改行や段落の字下げが枚数に与える影響とあわせて整理します。

関連ツール