Sintaxis JSONPath: qué selecciona cada símbolo con ejemplos
![Captura de pantalla con los datos de ejemplo book y bicycle en el campo de entrada JSON, $.store.book[*].title en el campo de expresión de ruta y, en el área de resultados, 2 coincidencias con los títulos de los dos libros en un array](/images/blog/es/jsonpath-syntax-explained/01-result.webp)
Contenido
No es fácil estar seguro a simple vista de que una expresión de ruta JSONPath apunta exactamente al valor que buscas. Símbolos como $, ., [ ], [*] o .. se calculan siguiendo reglas bien definidas.
Si conoces esas reglas, puedes rastrear a mano qué valores selecciona cada expresión. En este artículo usamos un único JSON de ejemplo para comprobar, uno por uno, qué elige realmente cada símbolo.
Resumen ①
$apunta al documento JSON completo, y.propiedado['propiedad']apuntan a una clave concreta de un objeto. ②[número]apunta al enésimo valor de un array (los negativos se cuentan desde el final), y[*]o.*apuntan a todos los valores de esa posición. ③..busca de forma recursiva en todas las profundidades, y el resultado siempre sale como array, sin importar cuántas coincidencias haya.
El problema cuando quieres extraer solo ciertos valores de una respuesta de API
Al trabajar con datos JSON es habitual encontrarse en la documentación y en el código de ejemplo expresiones con esta pinta: $.data.items[0].name. La clave de JSONPath es que una sola expresión puede apuntar directamente a un valor concreto en cualquier parte de una estructura JSON anidada.
El problema es saber si esa expresión funciona igual con tu propia estructura JSON. Si los nombres de las claves cambian o el orden del array es distinto, una expresión parecida puede apuntar a un valor completamente diferente o no encontrar nada.
Si dentro de los corchetes va un número o un *, qué cambia si pones * después de un ., hasta dónde busca exactamente ..: un solo símbolo de diferencia cambia el resultado, y no es fácil predecirlo solo con la vista.
Cómo calcularlo a mano solo con las reglas de los símbolos, sin herramienta
Cada implementación de JSONPath admite un rango de sintaxis algo distinto. Las cinco reglas que resumo aquí, aplicadas literalmente sobre el JSON de ejemplo de abajo, están dentro de un alcance que te permite reproducir el resultado a mano.
{
"store": {
"book": [
{ "title": "El almanaque de Charlie", "price": 22000 },
{ "title": "El inversor inteligente", "price": 18500 }
],
"bicycle": { "color": "red", "price": 129000 }
}
}
Las reglas son cinco.
$— apunta al documento completo. Si la expresión es solo$, el resultado es 1 array que contiene todo el JSON..propiedado['propiedad']— selecciona una clave con ese nombre dentro de un objeto.$.store.bicycle.colorapunta a un único valor, la cadena "red".[número]— selecciona el valor que ocupa esa posición en el array (empezando por 0). Los números negativos se cuentan desde el final del array.$.store.book[0]apunta al primer libro y$.store.book[-1]al último.[*]o.*— selecciona todos los valores de esa posición.$.store.book[*]selecciona los 2 objetos de libro que son elementos del array book...— busca el nombre que va después en todas las profundidades del documento.$..priceencuentra los dos price que hay dentro de book y el price de bicycle, tres en total.
Si seguimos en orden cómo se calcula realmente $.store.book[*].title, ocurre lo siguiente.
- Paso 1
$→ el objetivo es 1 elemento: el documento completo. - Paso 2
.store→ se reduce a 1 elemento: el objeto store. - Paso 3
.book→ se reduce a 1 elemento: el array book (el array en sí es el valor). - Paso 4
[*]→ se expande a cada elemento del array book, es decir, a 2 objetos de libro. - Paso 5
.title→ de cada objeto de libro que queda se extrae la clave title, y quedan 2 cadenas.
El resultado final es ["El almanaque de Charlie", "El inversor inteligente"] y el número de coincidencias es 2. Si aplicas estos cinco pasos tal cual, puedes predecir a mano el resultado de cualquier expresión de ruta.
Comprueba con nuestro Probador de consultas JSONPath, que es gratuito, si estos cinco pasos que has seguido a mano dan el mismo resultado con tu propio JSON y tu expresión de ruta.
Escribe el JSON y la expresión de ruta: la herramienta te muestra al instante los valores que coinciden y cuántos son. Los datos se procesan solo en tu navegador y no se envían a ningún servidor.
![Captura de pantalla con los datos de ejemplo book y bicycle en el campo de entrada JSON, $.store.book[*].title en el campo de expresión de ruta y, en el área de resultados, 2 coincidencias con los títulos de los dos libros en un array](/images/blog/es/jsonpath-syntax-explained/01-result.webp)
Los puntos que más confunden
Cuando empiezas con JSONPath hay varios puntos en los que el resultado sale distinto de lo que esperas. Esto es lo que pasa en realidad al introducir cada una de estas expresiones.
| Expresión introducida | Lo que ocurre en realidad |
|---|---|
$.store.book[1:3] (slice) | Se muestra "No hay valores coincidentes" sin ningún error. El texto entre corchetes no se interpreta como slice, sino que se trata tal cual como nombre de propiedad; y como book es un array, por nombre no encuentra nada. |
$.store.book[?(@.price>20000)] (expresión de filtro) | Por la misma razón, 0 coincidencias. La sintaxis de filtro ?() no se interpreta y todo el contenido de los corchetes se trata como nombre de propiedad. |
$.store.book[10] (índice fuera de rango) | 0 coincidencias sin error. Un índice que se sale de la longitud del array simplemente desaparece del resultado. |
$.store.book (seleccionar el array completo) | Todo el array book sale envuelto como un único valor coincidente. Es decir, el resultado es un array que contiene un array. |
$ solo | El resultado es un array de 1 elemento que contiene el documento completo. |
La razón por la que el filtro y el slice fallan en silencio es que el contenido de los corchetes solo se interpreta de tres formas: un número de índice, el comodín (*) y un nombre entre comillas.
Todo lo que no encaja en esas tres formas se procesa como "busca una clave con ese nombre", y como esa clave no existe en realidad, el resultado queda vacío.
Resumen
$apunta al documento completo;.propiedado['propiedad']apuntan a una clave de un objeto.[número]apunta a un índice del array (los negativos desde el final);[*]o.*apuntan a todos los valores de esa posición...busca de forma recursiva en todas las profundidades y reúne todos los valores que coinciden.- El resultado siempre sale como array, sin importar el número de coincidencias, y si no hay ninguna se muestra "No hay valores coincidentes" en lugar de un error.
- La expresión de filtro
?()y el slice[1:3]no están soportados, y la sintaxis que se sale de ese alcance no provoca un error, sino 0 coincidencias silenciosas.
Escribe el JSON y la expresión de ruta: la herramienta te muestra al instante los valores que coinciden y cuántos son. Los datos se procesan solo en tu navegador y no se envían a ningún servidor.
Preguntas frecuentes
¿Por qué el resultado siempre sale como array?
[*] y .. pueden encontrar varios valores a la vez, así que el resultado se muestra siempre como array, sin importar cuántas coincidencias haya. Incluso si escribes solo $ para apuntar al documento completo, obtienes un array con 1 elemento.
¿Por qué no se admiten la expresión de filtro ?() ni el slice [1:3]?
Esta herramienta solo interpreta seis formas de sintaxis: $, .propiedad, ['propiedad'], [número], [*]·.* y ...
Si introduces sintaxis fuera de ese alcance, como ?() o [1:3], no da error: el contenido de los corchetes se trata tal cual como nombre de propiedad y el resultado pasa a ser 0 coincidencias.
¿El JSON que introduzco se envía al servidor?
No. Tanto el análisis del JSON como la evaluación de la ruta se hacen solo dentro del navegador, y los datos que introduces no se envían ni se guardan en ningún servidor.
¿Cómo se calcula exactamente un índice negativo?
La posición real es la longitud del array más el índice negativo. Por ejemplo, en un array de 2 elementos, [-1] es 2 + (-1) = 1, es decir, el último elemento. Si la posición calculada se sale del rango del array, hay 0 coincidencias.
Este artículo está adaptado de nuestro original en coreano. Leer el original en coreano