JSONPath: язык запросов для извлечения данных из JSON

Что такое JSONPath?

JSONPath — это язык запросов для извлечения данных из JSON-документов. Подобно тому, как XPath навигирует XML-документы, JSONPath навигирует JSON-структуры с помощью компактного синтаксиса выражений. Он был формализован в RFC 9535 (февраль 2024 года) после многолетней неформальной спецификации.

Выражения JSONPath начинаются с $ (корневого элемента) и используют точечную нотацию или скобочную нотацию для обхода документа. Язык поддерживает подстановочные знаки, рекурсивный спуск, срезы массивов и фильтрующие выражения — что позволяет извлекать глубоко вложенные значения одним выражением.

Синтаксис JSONPath

JSONPath предоставляет несколько операторов для навигации и фильтрации JSON-структур.

• Root ($) — каждое выражение JSONPath начинается с $, представляющего корневой объект или массив JSON-документа
• Точечная нотация ($.store.book) — доступ к дочерним свойствам по имени, аналогично доступу к объектам JavaScript. Точки разделяют каждый уровень вложенности.
• Скобочная нотация ($['store']['book']) — альтернативный синтаксис с именами свойств в кавычках в скобках. Требуется, когда имена свойств содержат специальные символы или пробелы.
• Подстановочный знак (*) — соответствует всем элементам на текущем уровне. $.store.* возвращает все прямые дочерние элементы store; $[*] возвращает все элементы корневого массива.
• Рекурсивный спуск (..) — ищет всех потомков на любой глубине. $..price находит каждое поле 'price' в любом месте документа, независимо от уровня вложенности.
• Срезы массивов ([start:end:step]) — выбирают диапазон элементов массива. $[0:3] возвращает первые три элемента; $[-2:] возвращает последние два; $[::2] возвращает каждый второй элемент.

Примеры выражений JSONPath

Вот практические примеры, показывающие, как выражения JSONPath извлекают данные из реальных JSON-структур.

• Извлечение вложенных значений — $.users[0].name получает имя первого пользователя. $.config.database.host получает глубоко вложенное значение конфигурации.
• Фильтрация массивов — $.users[?(@.age > 18)] возвращает всех пользователей старше 18 лет. $.products[?(@.price < 50)] находит доступные по цене продукты. Фильтры используют @ для ссылки на текущий элемент.
• Многоуровневые запросы — $..author возвращает каждое поле автора на любой глубине. $.store.book[*].title возвращает все названия книг. $.orders[*].items[*].sku извлекает артикулы SKU по всем заказам и позициям.

Эти выражения можно комбинировать для создания мощных запросов. Например, $.store.book[?(@.price < 10)].title возвращает названия всех книг дешевле 10.

Распространённые случаи использования

JSONPath используется везде, где необходимо запрашивать или извлекать структурированные данные из JSON-документов.

• Извлечение ответов API — получайте конкретные поля из сложных ответов API без написания кода парсинга. Тестируйте выражения на примерных ответах перед кодированием.
• Парсинг конфигурации — извлекайте значения из JSON-файлов конфигурации в CI/CD-конвейерах, скриптах развёртывания и инструментах «инфраструктура как код»
• Анализ логов — запрашивайте структурированные JSON-логи для поиска конкретных событий, паттернов ошибок или метрик производительности в больших файлах логов
• Преобразование данных — используйте JSONPath в ETL-конвейерах для выбора, фильтрации и переформатирования JSON-данных во время операций импорта/экспорта

JSONPath против JQ против JMESPath

Существует несколько языков запросов для JSON-документов. У каждого свои преимущества и поддержка экосистемы.

• JSONPath — стандартный синтаксис запросов (RFC 9535), широко поддерживаемый в программных библиотеках (Java, Python, JavaScript, PHP). Лучший выбор для простого извлечения и фильтрации. Нет встроенного преобразования.
• JQ — командный JSON-процессор с мощным функциональным языком. Поддерживает преобразование, вычисления и форматирование вывода. Лучший выбор для написания скриптов и обработки данных в командной строке.
• JMESPath — язык запросов, используемый AWS CLI и Boto3. Более строгий синтаксис, чем у JSONPath, со встроенными функциями. Лучший выбор для интеграции с экосистемой AWS и программных запросов.

Часто задаваемые вопросы

JSONPath использует индексацию массивов с нуля или с единицы?

JSONPath использует индексацию массивов с нуля, что соответствует большинству языков программирования. $[0] возвращает первый элемент, $[1] — второй и т. д. Отрицательные индексы отсчитываются с конца: $[-1] возвращает последний элемент, $[-2] — предпоследний.

Как работают фильтрующие выражения в JSONPath?

Фильтрующие выражения используют синтаксис [?(expression)], где @ ссылается на текущий вычисляемый элемент. Можно использовать операторы сравнения (==, !=, <, >, <=, >=), логические операторы (&& и ||) и доступ к свойствам (например, @.name). Пример: $[?(@.status == 'active')] возвращает элементы, где status равен 'active'.

Все ли реализации JSONPath совместимы?

Не полностью. До RFC 9535 (2024) JSONPath не имел формального стандарта, и реализации различались. Распространённые различия включают синтаксис фильтрующих выражений, поведение рекурсивного спуска и обработку отсутствующих свойств. RFC 9535 направлен на стандартизацию поведения, но старые библиотеки могут следовать разным соглашениям. Всегда тестируйте выражения с вашей конкретной реализацией.