Guide des requêtes JSONPath : Extraire des données comme un pro

JSONPath est un langage de requête pour JSON, similaire à la façon dont XPath fonctionne pour XML. Lorsque vous travaillez avec des réponses API complexes et profondément imbriquées, JSONPath vous permet d'extraire exactement les données dont vous avez besoin sans écrire de boucles ni de conditions. Ce guide couvre la syntaxe, les opérateurs et les patterns concrets dont vous avez besoin.

Pourquoi JSONPath ?

Considérez une réponse API typique avec des données imbriquées :

{
  "store": {
    "books": [
      { "title": "Clean Code", "author": "Robert Martin", "price": 32.99, "tags": ["programming", "best-practices"] },
      { "title": "Design Patterns", "author": "Gang of Four", "price": 44.99, "tags": ["programming", "architecture"] },
      { "title": "The Pragmatic Programmer", "author": "Hunt & Thomas", "price": 39.99, "tags": ["programming", "career"] }
    ],
    "music": [
      { "title": "Kind of Blue", "artist": "Miles Davis", "price": 12.99 }
    ]
  }
}

Pour obtenir tous les titres de livres, vous pourriez écrire une boucle — ou utiliser JSONPath : $.store.books[*].title

Syntaxe de base

Notation par points vs notation par crochets

Les deux notations accèdent aux propriétés, mais la notation par crochets est requise pour les caractères spéciaux :

# Notation par points
$.store.books[0].title

# Notation par crochets (équivalent)
$['store']['books'][0]['title']

# Requis pour les clés avec caractères spéciaux
$['store']['price-range']

Opérations sur les tableaux

Indexation

$.store.books[0]          # Premier livre
$.store.books[-1]         # Dernier livre
$.store.books[0,2]        # Premier et troisième livres

Découpage

$.store.books[0:2]        # Deux premiers livres (index 0 et 1)
$.store.books[1:]         # Tous les livres sauf le premier
$.store.books[:2]         # Deux premiers livres
$.store.books[::2]        # Un livre sur deux

Jokers

$.store.books[*].title    # Tous les titres de livres
$.store.*                 # Toutes les collections du magasin (books, music)
$..title                  # Tous les titres à n'importe quelle profondeur
$..price                  # Tous les prix à n'importe quelle profondeur

L'opérateur de descente récursive (..) est particulièrement puissant pour extraire des valeurs indépendamment de leur position dans la hiérarchie.

Expressions de filtre

Les filtres sélectionnent des éléments en fonction de conditions :

# Livres à moins de 40 $
$.store.books[?(@.price < 40)]

# Livres d'un auteur spécifique
$.store.books[?(@.author == 'Robert Martin')]

# Livres avec plus de 2 tags
$.store.books[?(@.tags.length > 2)]

# Livres qui ont une propriété 'price'
$.store.books[?(@.price)]

Combiner des filtres

# Livres à moins de 40 $ avec le tag programming
$.store.books[?(@.price < 40 && @.tags[0] == 'programming')]

Exemples concrets

Extraction depuis des réponses API

API GitHub — obtenir tous les noms de dépôts :

$[*].name

API Météo — obtenir la température du jour :

$.daily[0].temp.day

API E-commerce — obtenir toutes les images de produits :

$.products[*].images[0].url

Extraction de configuration

Docker Compose — obtenir tous les noms de services :

$.services.*~

Package.json — obtenir tous les noms de dépendances :

$.dependencies.*~

JSONPath vs jq

JSONPath et jq sont tous deux des outils de requête JSON, mais ils servent des contextes différents :

Pour le traitement JSON en ligne de commande, jq est plus puissant. Pour intégrer des requêtes dans des applications ou utiliser des outils web, JSONPath est plus largement supporté.

Essayez les expressions JSONPath de manière interactive avec notre Explorateur JSON Path. Collez votre JSON, écrivez une requête et voyez les résultats instantanément.

Exemples d'implémentation

JavaScript (jsonpath-plus)

const { JSONPath } = require('jsonpath-plus');
const result = JSONPath({
  path: '$.store.books[?(@.price < 40)].title',
  json: data
});
// ["Clean Code", "The Pragmatic Programmer"]

Python (jsonpath-ng)

from jsonpath_ng import parse
expr = parse('$.store.books[*].title')
titles = [match.value for match in expr.find(data)]

RFC 9535 : Le standard JSONPath

En février 2024, JSONPath a été officiellement standardisé sous le nom RFC 9535. Cela résout les incohérences historiques entre les implémentations. Comportements standardisés clés :

• Les indices de tableau commencent à 0
• Les expressions de filtre utilisent @ pour l'élément courant
• La comparaison de chaînes est sensible à la casse
• Le résultat est toujours un tableau de valeurs correspondantes

Si vous choisissez une bibliothèque JSONPath, préférez-en une qui supporte RFC 9535 pour un comportement cohérent.

FAQ

Quelle est la différence entre JSONPath et JSON Pointer ?

JSONPath est un langage de requête qui peut correspondre à plusieurs valeurs en utilisant des jokers et des filtres. JSON Pointer (RFC 6901) est une syntaxe de chemin simple qui adresse exactement une valeur : /store/books/0/title. Utilisez JSONPath quand vous devez rechercher ou filtrer ; utilisez JSON Pointer quand vous connaissez le chemin exact.

JSONPath peut-il modifier des données JSON ?

Le JSONPath standard est en lecture seule — il extrait mais ne modifie pas les données. Certaines bibliothèques étendent JSONPath avec des opérations set/delete, mais celles-ci ne sont pas standard. Pour les transformations, envisagez jq (ligne de commande) ou écrivez du code applicatif. Pour visualiser et explorer la structure JSON, notre Formateur JSON vous aide à comprendre les données avant d'écrire des requêtes.

Ressources connexes

• Explorateur JSON Path — Testez les expressions JSONPath dans votre navigateur
• Bonnes pratiques de formatage JSON — Structurez votre JSON pour des requêtes plus faciles
• Guide de validation JSON Schema — Validez la structure que vos requêtes JSONPath attendent