JSONPath est un langage de requête pour extraire des valeurs d'un document JSON par chemin — le même rôle que joue XPath pour XML, une syntaxe familière pour qui a travaillé avec des systèmes administratifs ou bancaires français encore bâtis sur XML/SOAP dans leurs intégrations historiques.
Syntaxe de base
Une expression commence toujours par $, la racine du document. Ensuite, les champs sont accessibles par un point ($.user.name) ou par crochets ($['user']['name']), et les éléments d'un tableau par index ($.items[0]).
Sélectionner plusieurs valeurs à la fois
Le joker * sélectionne tous les éléments d'un niveau, tandis que .. est une descente récursive — il trouve un champ à n'importe quelle profondeur sans connaître le chemin exact. Des filtres comme [?(@.price < 10)] sélectionnent des éléments de tableau selon une condition qui ressemble à une expression de programmation.
À quoi cela sert
- Extraire rapidement un champ d'une grosse réponse d'API pendant un débogage, sans écrire de script.
- Filtrer des logs ou des événements JSON selon une condition à la volée.
- Lire une valeur dans un fichier de configuration sans écrire de parseur à la main.
JSONPath contre XPath : le décalage d'indexation classique
Ceux qui viennent de XPath, où l'indexation des nœuds commence à 1 (book[1] est le premier élément), se trompent souvent en passant à JSONPath, où l'indexation commence à 0 — book[1] est déjà le deuxième élément. Cette seule différence explique une bonne part des bugs lors de la migration d'anciennes intégrations XML/XPath vers des API JSON.
Clés avec points ou espaces
Si le nom d'un champ contient lui-même un point, un tiret ou une espace (par exemple une clé littérale "user.name", et non des champs imbriqués), la notation pointée $.user.name devient ambiguë — le parseur la lit comme les champs imbriqués user et name. Dans ce cas, la clé doit être placée entre crochets avec des guillemets : $['user.name'].