JSONPath - язык запросов к JSON, как XPath к XML: вы указываете на узлы вместо вложенных циклов. В большинстве дней хватает горстки токенов - `$`, `@`, точки, скобки, `*`, `..`, срез и простой фильтр `[?()]`. Это руководство - короткий список, а не клон всего RFC. Вставьте пример ниже в JSONPath Tester и проверьте каждое выражение в браузере - ничего не загружается.
Краткий ответ
Каждый путь начинайте с `$` (корень документа). `@` внутри фильтра - текущий элемент. Для будней удобно `$.store.book[*].title`; `$['store']['book'][0]` - когда в ключе пробелы или зарезервированные символы. `$..author` находит поле на любой глубине. Фильтры вида `$.store.book[?(@.price < 10)]`. RFC 9535 - современный диалект, старые примеры Goessner - фольклор, пока не проверите.
Один пример payload
Каждый пример ниже использует классический документ книжного магазина (ту же форму делят многие туториалы по JSONPath). Держите его открытым, пока читаете:
- `store.book` - массив объектов с `category`, `author`, `title`, `price` и иногда `isbn`.
- `store.bicycle` - вложенный объект с `color` и `price`.
- Если payload пришел одной строкой, сначала отформатируйте в JSON Minifier & Formatter, затем запрашивайте.
$ и @
`$` - корень вставленного JSON: весь объект или массив. Каждое полезное выражение начинается с него. `@` имеет смысл только внутри фильтра: "текущий проверяемый элемент". Вне фильтра `@` - не свободный курсор.
- `$` - корень документа.
- `@.price` внутри `[?()]` - поле `price` проверяемого элемента.
- `$.store.book[?(@.isbn)]` - книги с ключом `isbn` (проверка существования).
- Путь без `$` строгие тестеры обычно отклоняют - всегда начинайте с `$`.
Точка против скобок
Точечная нотация - сокращение для простых идентификаторов: `$.store.book`. Скобочная - явная форма: `$['store']['book']`. Скобки - когда ключ не простой идентификатор (пробелы, дефисы, цифра в начале) или нужен normalized path RFC 9535, как в таблицах совпадений.
- `$.store.bicycle.color` - для обычных ключей.
- `$['content-type']` - когда ключ не похож на JS-идентификатор.
- `$['store']['book'][0]['title']` - единый normalized path к одному узлу (стиль RFC 9535 §2.7).
- Индексы всегда в скобках: `$.store.book[0]`, не `$.store.book.0`.
* и ..
`*` - wildcard "каждый потомок на этом уровне". `..` - рекурсивный спуск: обход дерева и сбор совпадений на любой глубине. Wildcard остается мелким; спуск может удивить на больших документах.
- `$.store.book[*].title` - title каждой книги (один уровень элементов массива).
- `$.store.*` - и `book`, и `bicycle` под `store`.
- `$..author` - каждый `author` под корнем.
- `$..price` - цены книг и велосипеда вместе - сузьте путь, если нужен только один.
Срезы
Срезы массива используют python-подобный `start:end:step` в скобках. Пропущенные концы - "с начала" или "до конца". Отрицательные индексы с конца, если движок поддерживает.
- `$.store.book[0:2]` - первые две книги (индексы 0 и 1).
- `$.store.book[-1:]` - последняя книга, если разрешены отрицательные индексы.
- `$.store.book[::2]` - каждая вторая книга, если поддерживается step.
- Срезы выбирают элементы массива; за ними можно цепочкой поле: `$.store.book[0:2].title`.
Простой фильтр
Фильтры в `[?(...)]` оставляют элементы, где выражение истинно. `@` - текущий элемент. Сравнения обычно не приводят типы как loose JavaScript - `1 == "1"` часто ложь. Держите фильтры простыми: равенство, неравенство, числа, `&&`, `||`, `!`, существование.
- `$.store.book[?(@.price < 10)]` - дешевые книги.
- `$.store.book[?(@.price < 10 && @.category == 'fiction')].title` - фильтр, затем поле.
- `$.store.book[?(@.isbn)]` - элементы с `isbn`.
- Фильтр на массив, который сканируете, а не на одиночный object root, если корень сам не массив.
RFC 9535 против старого диалекта Goessner
Статья Stefan Goessner 2007 года популяризировала JSONPath, и многие библиотеки до сих пор копируют ее примеры. RFC 9535 (2024) - стандарт IETF: яснее грамматика, normalized paths и меньше лазеек "eval чего угодно". Script-селекторы вроде `[(@.length-1)]` и свободный JavaScript в фильтрах - старый дикий запад, не безопасный браузерный тестер.
- RFC 9535 - стандартизованные операторы, normalized paths вроде `$['store']['book'][0]`, для совместимых реализаций.
- Примеры эпохи Goessner - везде в блогах; проверяйте перед продакшеном.
- Подмножества без eval - то, что нужно для вставленных API payload. Отклоняйте script-селекторы; не выполняйте путь как JavaScript.
- Когда два инструмента расходятся, смотрите заявленный диалект - а не на "ощущение" правильности.
Не полная спецификация
Эта статья - шпаргалка по выражениям на каждый день. Нормативные детали - в RFC 9535. Для приватных прогонов на своем JSON - JSONPath Tester.
Пять примеров copy-paste
На примере книжного магазина попробуйте по порядку:
- `$.store.book[*].title` - все title списком.
- `$..author` - каждый author рекурсивным спуском.
- `$.store.book[0:2]` - первые два объекта книг.
- `$.store.book[?(@.price < 10)]` - книги дешевле 10.
- `$.store.book[?(@.price < 10)].title` - тот же фильтр, только title.
После плоского списка записей может понадобиться таблица - пропустите JSON-массив объектов через JSON to CSV Converter. Для вложенных API-blob, которые еще исследуете, оставайтесь в JSONPath, пока форма не ясна.
Частые вопросы
Каждый JSONPath начинается с $?
На практике да. `$` именует корень. Строгие инструменты отклоняют пути без него.
Когда использовать @?
Только внутри фильтров `[?()]`, как текущий элемент. Не замена `$` в начале пути.
Почему ноль совпадений?
Валидный путь может ничего не найти. Часто: фильтр по object root вместо массива, опечатка в ключе или ожидание приведения типов JavaScript. Попробуйте `$..field`, чтобы убедиться, что поле есть, затем сузьте.
JSONPath то же самое, что JMESPath или jq?
Нет. Схожая идея, другой синтаксис и библиотеки. Один диалект на кодовую базу и придерживайтесь его.
Безопасно протестировать приватный ответ API?
Да, если вычислитель в браузере без загрузки. JSONPath Tester для этого - вставка, запрос, копирование извлеченного JSON или normalized paths.
Попробуйте в ToolsMinify
Все инструменты ниже работают в браузере - бесплатно, без регистрации, без загрузки на сервер:
- JSONPath Tester - вставьте JSON, выполните выражение, скопируйте совпадения или извлеченные значения.
- JSON Minifier & Formatter - pretty-print или минификация payload перед запросом.
- JSON to CSV Converter - плоский JSON-массив объектов в CSV после извлечения.
- All developer tools - полный указатель категории.
Попробуйте бесплатно
Откройте JSONPath Tester, загрузите пример книжного магазина и вставьте `$.store.book[?(@.price < 10)].title`. Должны появиться дешевые title - все на вашем устройстве.