La primera vez que escribí una expresión JSONPath que importaba, me equivoqué tres veces antes de que funcionara, y solo supe que estaba mal porque la puerta de enlace API que estaba configurando devolvió una política vacía en lugar del campo que quería. No había bucle de retroalimentación. Editaría la expresión, la volvería a implementar y esperaría. Una vez que comencé a mantener abierto un probador JSONPath en otra pestaña, ese mismo trabajo tomó dos minutos en lugar de una tarde. Esta guía trata sobre cómo uso el Probador JSONPath en Toolz.dev, lo que realmente hace la sintaxis y las pequeñas trampas que hacen que una expresión no devuelvan nada cuando estabas seguro de que debería coincidir.
TL;Dr: JSONPath es un lenguaje de consulta para JSON, como lo es XPath para XML. Un probador JSONPath evalúa una expresión como
$.store.book[*].authorcontra un documento y devuelve cada valor coincidente más su ruta. El Probador JSONPath hace esto completamente en su navegador, con soporte para comodines, descenso recursivo, cortes, uniones y expresiones de filtro, para que pueda crear y depurar una consulta con datos reales antes de pegarla en código.
¿qué es JSONPath?
JSONPath es una sintaxis compacta para seleccionar partes de un documento JSON. Escribe una ruta corta que describe una ruta a través de los datos y al evaluarla devuelve el valor o valores en esa ruta. La idea surge de Stefan Goessner & #39;s Propuesta de 2007, que reflejaba deliberadamente XPath para que cualquiera que hubiera consultado XML se sintiera como en casa. Durante años no hubo ninguna especificación formal, solo ese artículo y una familia de implementaciones que en su mayoría coincidían, y a principios de 2024 se publicó el IETF RFC 9535 para precisar la gramática.
Conoces JSONPath con más frecuencia de lo que cabría esperar. Es el lenguaje selector en herramientas de prueba API como Postman y Karate, en Kubernetes kubectl formato de salida, en AWS CloudWatch y Step Functions, en procesadores de registros y en docenas de plataformas de código bajo donde un usuario necesita extraer un campo de la carga útil de un webhook sin escribir código. Aprenderlo una vez vale la pena en todos ellos.
El modelo mental es simple. Un documento JSON es un árbol. Los objetos tienen ramas con nombre, las matrices tienen ramas numeradas y las hojas son sus valores escalares. Una expresión JSONPath es un conjunto de instrucciones para caminar por ese árbol, y el resultado es cada hoja o subárbol en el que aterrizas. Donde se vuelve poderoso es que una sola expresión puede aterrizar en muchos lugares a la vez.
¿qué hace realmente un probador JSONPath?
Un probador toma dos entradas, su JSON y una expresión, y le muestra cada nodo que selecciona la expresión. Eso suena obvio, pero el valor está en la retroalimentación. Cuando una expresión no devuelve nada o devuelve más de lo que esperabas, un evaluador convierte un juego de adivinanzas en una verificación de dos segundos, porque puedes ver exactamente qué nodos coinciden y ajustar un carácter a la vez.
En Toolz.dev el flujo es corto. Pegue un documento JSON o cargue la librería de muestra que utilizan la mayoría de los tutoriales de JSONPath, escriba una expresión y evalúe. La herramienta enumera cada valor coincidente con un recuento en ejecución y puede cambiar la salida entre tres vistas. Los valores le brindan solo los resultados como una matriz JSON. Las rutas le brindan la ubicación normalizada de cada coincidencia, que es la forma más rápida de descubrir la expresión que realmente necesita. Las entradas te brindan ambas juntas, para que puedas ver la ruta y el valor una al lado de la otra.
La razón para comparar datos reales en lugar de razonar sobre ellos en su cabeza es que JSON de la naturaleza es más desordenado que los ejemplos. Un campo es a veces un objeto y otras veces una matriz. Falta una clave que esperabas en la mitad de los registros. Un número llegó como una cadena. Al ejecutar la expresión contra la carga útil real, se obtienen esas sorpresas inmediatamente en lugar de en el momento de la implementación.
¿Cómo selecciono elementos de una matriz?
Las matrices son donde ocurre la mayor parte del trabajo de JSONPath y hay cuatro formas de abordarlas.
Un único índice selecciona un elemento. $.store.book[0] devuelve el primer libro y JSONPath, como la mayoría de los idiomas, cuenta desde cero. Un índice negativo cuenta desde el final, entonces $.store.book[-1] devuelve el último libro sin necesidad de saber cuántos hay. Esa forma negativa es realmente útil cuando desea el elemento más reciente en un registro o la última entrada en un feed.
Un comodín selecciona cada elemento. $.store.book[*] devuelve los cuatro libros y $.store.book[*].author devuelve el autor de cada uno, brindándole una gama limpia de autores. El comodín también funciona en objetos, donde $.store.* devuelve todos los valores del objeto de la tienda independientemente de la clave.
Un sindicato selecciona un conjunto específico. $.store.book[0,2] devuelve el primer y tercer libro, y la misma sintaxis de coma funciona con nombres $['store']['bicycle'] y las claves entre corchetes le permiten direccionar claves que contienen espacios o puntuación que la forma de punto no puede.
Una porción selecciona un rango, tomando prestado Python's start:end:step forma. $.store.book[:2] toma los dos primeros, $.store.book[1:3] toma un rango medio con el índice final exclusivo $.store.book[::2] toma cada segundo elemento, y $.store.book[::-1] invierte la matriz. Los cortes son la parte menos conocida de la sintaxis y la que ahorra más escritura una vez que la tienes.
¿qué hace el doble punto?
El doble punto es el descenso recursivo y es la característica que hace que JSONPath parezca una búsqueda más que una ruta. $..author encuentra cada author clave en cualquier parte del documento, sin importar cuán profundamente esté anidado, y $..* devuelve todos los valores en todos los niveles. Cuando no sabes la forma exacta de un documento, o cuando el mismo campo aparece a varias profundidades, el descenso recursivo los encuentra todos en una sola expresión.
Considere la librería de muestra. $..price devuelve cinco valores, los cuatro precios de los libros y el precio de la bicicleta, porque desciende a cada objeto y recoge cada uno price encuentra. Una llanura $.store.book[*].price devolvería sólo los cuatro precios de los libros, porque recorre una ruta fija. La diferencia entre esas dos expresiones es la diferencia entre pedir precios en un lugar conocido y pedir precios en cualquier lugar.
El descenso recursivo es lo suficientemente poderoso como para ser peligroso, en el sentido de que puede igualar más de lo que quisiste decir. Precisamente por eso es importante aquí un evaluador. Correr $..name contra una carga útil desconocida y es posible que descubra que coincide con un nombre de usuario, un nombre de producto y un nombre de archivo que no tenía idea de que compartía una clave. Ver las rutas en la salida le indica si debe limitar la expresión antes de confiar en ella.
¿cómo funcionan las expresiones de filtro?
Un filtro conserva sólo los elementos para los cuales una condición es verdadera y está escrito [?(...)] en compañía de @ representando el elemento actual. $.store.book[?(@.price < 10)] devuelve los libros más baratos que diez. Dentro del filtro puedes comparar un campo con un literal con los operadores ==, !=, <, <=, >y >=, pruebe la mera presencia de un campo y combine condiciones con && y ||.
Algunos ejemplos concretos dejan clara la forma:
$.store.book[?(@.category == "fiction")]selecciona los títulos de ficción.$.store.book[?(@.price < 10 && @.category == "fiction")]se reduce a ficción barata.$.store.book[?(@.isbn)]selecciona sólo los libros que tienen un ISBN, utilizando la existencia en lugar de la comparación.$.vals[?(@ > 2)]filtra una simple matriz de números, donde@por sí solo se refiere al elemento mismo.
El error de filtro más común es una falta de coincidencia de tipos. En JSON, "12" y 12 son valores diferentes, por lo que un filtro que compara un campo numérico con un número citado, o un campo de cadena con un número simple, silenciosamente no coincide con nada. Cuando un filtro te sorprende, lo primero que debes comprobar es si el campo y el literal son del mismo tipo. Probar la expresión con los datos reales, donde puedes ver los valores reales, es como se detecta en segundos en lugar de después de una implementación fallida.
JSONPath versus JSON Pointer versus JSON diff
Todas estas tres herramientas tocan la estructura JSON, pero responden preguntas diferentes y elegir la incorrecta hace perder el tiempo. Así es como se comparan:
| acceso | Respuestas | partidos | mejor para |
|---|---|---|---|
| JSONPath | ¿qué nodos satisfacen esta consulta? | Cero, uno o muchos | Extrayendo campos, filtrando matrices, explorando formas desconocidas |
| Puntero JSON (RFC 6901) | ¿Qué hay en esta ubicación exacta? | Siempre exactamente uno | Hacer referencia a un único campo fijo, como en el esquema JSON $ref |
| Diferencia JSON | ¿Qué cambió entre dos documentos? | Un conjunto de cambios | Comparando dos versiones de los mismos datos |
Puntero JSON, definido en RFC 6901, aborda un lugar preciso con un camino separado como /store/book/0/title, y nunca utiliza comodines ni filtros. Busque cuando necesite nombrar un solo campo sin ambigüedades. Busque JSONPath cuando una sola expresión debería seleccionar un conjunto de campos. Y cuando su verdadera pregunta es qué difiere entre dos cargas útiles en lugar de qué selecciona una consulta, a Diferencia de JSON es la herramienta adecuada. Saber cuál de los tres realmente necesitas es la mitad de la batalla.
¿Por qué mi expresión no arroja resultados?
Un resultado vacío casi siempre proviene de una de las pocas causas, y un evaluador le permite descartarlas rápidamente.
El primero es un desajuste estructural. Usted escribió $.data.items.name cuando items es una matriz, por lo que necesitabas $.data.items[*].name con un comodín. La forma de punto entra en un objeto y una matriz no es un objeto con a name clave, entonces la ruta termina. Cambiar la vista de salida a rutas y pasar la expresión un segmento a la vez le muestra exactamente dónde deja de coincidir.
El segundo es un error ortográfico o de carcasa. Las claves JSON distinguen entre mayúsculas y minúsculas, por lo que $.userId no coincidirá con a userID el campo y un espacio final o un error tipográfico en el nombre de una clave producen la misma nada silenciosa. Debido a que el evaluador le muestra el documento justo al lado de la expresión, estos son rápidos de detectar.
El tercero, como se mencionó anteriormente, es una discrepancia de tipo de filtro, donde una comparación numérica se ejecuta contra un valor de cadena o al revés. El cuarto supone que existe una clave en cada elemento cuando existe solo en algunos. Los filtros de existencia y descenso recursivo son los remedios habituales. En todos los casos, la solución proviene de observar qué nodos toca la expresión, que es precisamente para qué sirve un probador.
Si construye en toda la pila como lo hago yo, moviéndose entre una API de Laravel, una interfaz de React y algún script de shell ocasional, JSONPath aparece en los tres, y un probador basado en navegador que nunca carga sus datos es la herramienta que mantengo. más cercano. Escribí sobre cómo utilidades como esta encajan en un kit más amplio en el Kit de herramientas para desarrolladores web, y el caso para mantener este tipo de trabajo del lado del cliente está en el Privacidad de datos en herramientas en línea guía.
¿cómo encaja esto con el resto de mi flujo de trabajo JSON?
Un probador JSONPath rara vez es la única herramienta abierta. Cuando el JSON que estoy consultando llegó minificado o con sangría inconsistente, lo ejecuto a través de Formateador JSON primero para poder leer la estructura mientras escribo la expresión. El formateador y el probador juntos son cómo paso de una respuesta API ilegible a una consulta funcional.
Una vez que sé qué campos me importan, el siguiente paso suele ser remodelarlos. Si necesito introducir los valores seleccionados en una hoja de cálculo o en un archivo de entorno, el Aplanador JSON convierte la estructura anidada en claves de notación de puntos y su sintaxis de ruta está lo suficientemente cerca de JSONPath como para que las dos se refuercen entre sí. Si estoy creando un tipo para los datos en TypeScript, el JSON a mecanografiado converter genera la interfaz y, si necesito validar la forma en lugar de simplemente leerla, Generador de esquemas JSON produce un esquema al que puedo agregar restricciones. JSONPath es el paso de exploración; Estas herramientas son lo que hago con lo que encuentro.
Vale la pena repetir el punto de privacidad porque el trabajo de JSONPath suele ocurrir con datos confidenciales. Las respuestas de API contienen tokens, registros de usuario e ID internos, y pegarlos en una herramienta del lado del servidor significa confiar en otra persona 's logs. Debido a que el probador Toolz.dev analiza y evalúa completamente en su navegador, nada de eso deja su máquina y la herramienta sigue funcionando con la red desconectada. Esa es la diferencia entre una herramienta que puedes usar en una carga útil de preparación y otra que puedes usar en la real.
Preguntas frecuentes
¿para qué se utiliza JSONPath?
JSONPath se utiliza para seleccionar y extraer partes de un documento JSON con una sola expresión. Es el lenguaje de consulta en las herramientas de prueba de API, el formato de salida de Kubernetes, los servicios en la nube como las funciones de paso de AWS y muchas plataformas de código bajo, dondequiera que alguien necesite extraer un campo o filtrar una matriz de una carga útil JSON sin escribir código de procedimiento.
¿cómo selecciono cada elemento de una matriz en JSONPath?
Utilice el comodín, entonces $.items[*] devuelve cada elemento de la matriz de elementos y $.items[*].id devuelve el id de cada uno. También puedes seleccionar un elemento por índice con $.items[0], el último elemento con el índice negativo $.items[-1], un conjunto con una unión como $.items[0,2], o un rango con una rebanada como $.items[1:3].
¿qué significa el doble punto en JSONPath?
El doble punto es el descenso recursivo, que busca a cualquier profundidad. $..author encuentra cada clave de autor en cualquier parte del documento, sin importar cuán profundamente anidado esté, y $..* devuelve todos los valores en todos los niveles. Es la forma más rápida de extraer un campo de un documento cuya estructura exacta no conoce de antemano.
¿cómo funcionan las expresiones de filtro en JSONPath?
Un filtro [?(...)] mantiene sólo los elementos para los cuales una condición es verdadera, con @ refiriéndose al elemento actual. Por ejemplo $.book[?(@.price < 10)] devuelve libros más baratos que diez y puedes combinar condiciones con && y ||, como por ejemplo [?(@.price < 10 && @.category == "fiction")]. También puedes probar la existencia de un campo 's con [?(@.isbn)].
¿por qué mi expresión JSONPath no devuelve nada?
Las dos causas más comunes son una discrepancia estructural y una discrepancia de tipo. Compruebe que cada clave exista y esté escrita con la carcasa exacta, y que haya utilizado un comodín donde los datos sean una matriz en lugar de un objeto. En filtros, recuerde que "12" y 12 son valores diferentes, así que compare un campo de cadena con un valor cotizado y un campo numérico con un número simple.
¿cuál es la diferencia entre JSONPath y JSON Pointer?
Un puntero JSON aborda una ubicación exacta, como /store/book/0/title, y siempre devuelve un valor único. JSONPath es un lenguaje de consulta donde una sola expresión puede hacer coincidir muchos nodos a la vez a través de comodines, descenso recursivo y filtros. Utilice un puntero para hacer referencia a un campo fijo y JSONPath para seleccionar un conjunto de campos o filtrar una colección.
¿Puedo ver el camino de cada partido, no sólo el valor?
Sí. Cambie el modo de salida a rutas para obtener la ubicación normalizada de cada coincidencia, o entradas para reunir la ruta y el valor. Ver las rutas reales es la forma más rápida de refinar una expresión hasta que seleccione exactamente los nodos que pretendía, lo cual es especialmente útil con el descenso recursivo.
¿mi JSON se carga cuando uso el probador?
No. El documento se analiza y la expresión se evalúa en su navegador con JavaScript, por lo que no se transmite, registra ni almacena nada. Puede confirmarlo mirando la pestaña de red mientras ejecuta una consulta o desconectándose de Internet, porque el probador sigue funcionando sin conexión una vez que la página se ha cargado.
Pruébalo con tus propios datos con el gratis Probador JSONPath. Evalúa comodines, descendencia recursiva, cortes, uniones y expresiones de filtro completamente en su navegador, sin cargar nada.
