JSONPathの使い方: 記号ごとの意味を例で確認
![JSON入力欄にbook・bicycleのサンプルデータ、パス式入力欄に$.store.book[*].titleが入力され、結果エリアに一致2件として2冊の書名が配列で表示されている画面](/images/blog/ja/jsonpath-syntax-explained/01-result.webp)
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つです。
$— ドキュメント全体を指します。パス式が$だけなら、結果はこのJSON全体が入った配列1つです。.プロパティまたは['プロパティ']— オブジェクトからその名前のキーを1つ選択します。$.store.bicycle.colorは文字列 "red" 1つを指します。[数値]— 配列からその順番(0から始まる)の値を1つ選択します。負の数は配列の末尾から数えます。$.store.book[0]は最初の本を、$.store.book[-1]は最後の本を指します。[*]または.*— その位置にあるすべての値を選択します。$.store.book[*]はbook配列の要素である本のオブジェクト2つをすべて選択します。..— 後ろに続く名前を、ドキュメントのすべての階層で探します。$..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とパス式でも正しく計算されるか、無料ツールで確認してみましょう。
JSONとパス式を入力すると、一致した値と件数をその場で表示します。データはブラウザ内だけで処理され、サーバーには送信されません。
![JSON入力欄にbook・bicycleのサンプルデータ、パス式入力欄に$.store.book[*].titleが入力され、結果エリアに一致2件として2冊の書名が配列で表示されている画面](/images/blog/ja/jsonpath-syntax-explained/01-result.webp)
よくつまずくポイント
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件として現れます。
JSONとパス式を入力すると、一致した値と件数をその場で表示します。データはブラウザ内だけで処理され、サーバーには送信されません。
よくある質問
結果がなぜいつも配列で返ってくるのですか?
[*] や .. は複数の値を一度に探せるため、一致件数にかかわらず結果を配列に統一して表示しています。$ だけを入力してドキュメント全体を指す場合も、要素1件だけの配列として返ります。
フィルター式 ?() やスライス [1:3] はなぜサポートしていないのですか?
このツールが解釈するのは $、.プロパティ、['プロパティ']、[数値]、[*]・.*、.. の6つの文法だけです。
?() や [1:3] のようにこの範囲を外れた文法を入れると、エラーではなく大括弧の中身をそのままプロパティ名として扱い、マッチ0件として処理します。
入力したJSONはサーバーに送信されますか?
いいえ。JSONのパースもパス式の評価もすべてブラウザの中だけで行われ、入力したデータがサーバーに送信されたり保存されたりすることはありません。
負のインデックスは具体的にどう計算されるのですか?
配列の長さに負のインデックスを足した値が実際の位置になります。たとえば要素が2つある配列で [-1] は 2 + (-1) = 1番目、つまり最後の要素を指します。計算した位置が配列の範囲を外れる場合はマッチ0件になります。
この記事は韓国語の原文をもとに作成しています。 韓国語の原文を読む