JSONPathはパスを指定してJSONドキュメントから値を取り出すクエリ言語で、XMLに対するXPathと同じ役割を果たす。日本の官公庁システムや金融機関では歴史的にXML/SOAPベースの連携が多く残っており、そこからJSON APIへ移行した開発者にはこの構文が馴染み深いはずだ。
基本構文
式は必ず$から始まり、これはドキュメントのルートを表す。そこからドット表記（$.user.name）や角かっこ表記（$['user']['name']）でフィールドにアクセスし、配列の要素にはインデックス（$.items[0]）でアクセスする。
複数の値をまとめて選択する
ワイルドカード*はある階層のすべての要素を選択し、..は再帰的な探索で、正確なパスを知らなくても任意の深さにあるフィールドを見つけ出す。[?(@.price < 10)]のようなフィルターは、プログラミング言語の式に似た条件で配列の要素を選択する。
実務でどう使われるか
- デバッグ中に大きなAPIレスポンスから特定のフィールドをスクリプトなしで素早く取り出す。
- JSON形式のログやイベントを、その場で条件に基づいてフィルタリングする。
- パーサーを自作せずに設定ファイルから値を読み取る。
JSONPath対XPath: インデックスのずれによる典型的なミス
XPathではノードのインデックスが1から始まる（book[1]が最初の要素）ため、そこからJSONPathに移った開発者はよくつまずく — JSONPathではインデックスが0から始まり、book[1]はすでに2番目の要素になる。この違いだけで、古いXML/XPathベースの連携をJSON APIに移行する際のバグの少なからぬ部分を占めている。
ドットやスペースを含むキー
フィールド名自体にドット、ハイフン、スペースが含まれている場合（ネストしたフィールドではなく、文字どおりのキー"user.name"である場合）、ドット表記$.user.nameは曖昧になる — パーサーはこれをネストしたフィールドuserとnameとして読み取ってしまう。このような場合は、キーを引用符付きの角かっこで囲む必要がある: $['user.name']。