JSONPath: мова запитів для вилучення даних з JSON

Що таке JSONPath?

JSONPath — це мова запитів для вилучення даних із JSON-документів. Так само як XPath навігує XML-документами, JSONPath навігує структурами JSON за допомогою стислого синтаксису виразів. Він був формалізований у RFC 9535 (лютий 2024) після багатьох років неформальної специфікації.

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

Синтаксис JSONPath

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

• Корінь ($) — кожен вираз 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 повертає кожне поле 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 прагне стандартизувати поведінку, але старіші бібліотеки можуть все ще дотримуватися різних угод. Завжди перевіряйте вирази у своїй конкретній реалізації.