JSONPath es un lenguaje de consultas para extraer valores de un documento JSON siguiendo una ruta, el mismo papel que cumple XPath para XML — algo familiar para quienes trabajaron con sistemas de administración pública o banca en España y Latinoamérica que todavía usan XML y SOAP en sus integraciones heredadas.
Sintaxis básica
Una expresión siempre empieza con $, la raíz del documento. Desde ahí, se accede a los campos con un punto ($.usuario.nombre) o con corchetes ($['usuario']['nombre']), y a los elementos de un array por índice ($.items[0]).
Seleccionar varios valores a la vez
El comodín * selecciona todos los elementos de un nivel, mientras que .. es descenso recursivo: encuentra un campo a cualquier profundidad sin importar la ruta exacta. Los filtros como [?(@.price < 10)] seleccionan elementos de un array según una condición parecida a una expresión de programación.
Para qué se usa
- Extraer un campo concreto de una respuesta de API grande al depurar, sin escribir un script.
- Filtrar registros o eventos en formato JSON según una condición al vuelo.
- Leer un valor de un archivo de configuración sin escribir un analizador a mano.
JSONPath frente a XPath: el desfase de uno que confunde
Quien viene de XPath, donde la indexación de nodos empieza en 1 (book[1] es el primer elemento), suele equivocarse al pasar a JSONPath, donde la indexación empieza en 0 — book[1] ya es el segundo elemento. Esa diferencia explica buena parte de los errores al migrar integraciones XML/XPath antiguas a APIs basadas en JSON.
Claves con puntos o espacios
Si el nombre de un campo contiene un punto, un guion o un espacio (por ejemplo, una clave literal "usuario.nombre" en vez de campos anidados), la notación de puntos $.usuario.nombre se vuelve ambigua — el analizador la interpreta como los campos anidados usuario y nombre. En ese caso hay que usar corchetes con comillas: $['usuario.nombre'].