JSONPath — язык запросов для выборки значений из JSON, концептуально то же самое, что XPath для XML. Для тех, кто работал с российскими госсистемами и банковским API прошлого поколения на XML/SOAP (например, старые версии интеграций с 1С или ФНС), синтаксис покажется знакомым — только вместо /store/book[1]/title пишут $.store.book[0].title.
Базовый синтаксис
Выражение всегда начинается с $ — корень документа. Дальше идёт обращение к полям через точку ($.user.name) или через квадратные скобки ($['user']['name']), а к элементам массива — по индексу ($.items[0]).
Выборка нескольких значений сразу
Символ * выбирает все элементы на определённом уровне, а .. — рекурсивный спуск, находящий поле на любой глубине документа. Фильтры вида [?(@.price < 10)] позволяют выбирать элементы массива по условию, похожему на выражение в языке программирования.
Зачем это нужно
- Быстро проверить или вытащить конкретное поле из большого ответа API при отладке.
- Написать условие фильтрации логов или событий в формате JSON без отдельного скрипта.
- Достать значение из конфигурационного файла, не написав парсер вручную.
JSONPath против XPath: почему индексация с нуля путает
Разработчики, перешедшие с XML/XPath (где индексация массивов начинается с 1, как в book[1] — первый элемент) на JSONPath, регулярно ошибаются на единицу: в JSONPath индексация массива начинается с 0, и book[1] означает уже второй элемент. Эта разница — частый источник багов при миграции старых XML-интеграций на JSON.
Ключи с точками или пробелами
Если имя поля само содержит точку, дефис или пробел (например, ключ "user.name" как единая строка, а не вложенность), запись через точку $.user.name станет неоднозначной — парсер прочитает её как вложенные поля user и name. В таких случаях ключ обязательно берут в квадратные скобки с кавычками: $['user.name'].