Guía de consultas JSONPath: Cómo buscar datos JSON

JSON se ha convertido en el lenguaje universal de la Web. Las APIs devuelven JSON, los archivos de configuración usan JSON y las bases de datos almacenan documentos JSON. Pero a medida que las estructuras JSON se vuelven más grandes y más profundamente anidadas, encontrar valores específicos se vuelve cada vez más difícil. Aquí es donde entra JSONPath. JSONPath es un lenguaje de consulta que te permite navegar y extraer datos de documentos JSON usando expresiones de ruta concisas, tal como XPath lo hace para XML. Esta guía cubre todo, desde la sintaxis básica hasta el filtrado avanzado, con ejemplos prácticos que puedes aplicar inmediatamente.

¿Qué es JSONPath?

JSONPath es un lenguaje de consulta JSON propuesto originalmente por Stefan Goessner en 2007. Proporciona una sintaxis compacta para seleccionar nodos de documentos JSON, similar a cómo los selectores CSS apuntan a elementos HTML o las expresiones XPath apuntan a nodos XML. En lugar de escribir bucles y lógica condicional para recorrer estructuras JSON, simplemente escribes una expresión que describe la ruta hacia los datos deseados.

Las expresiones JSONPath comienzan desde el nodo raíz del documento JSON y navegan a través de objetos y arrays hasta el valor deseado. El lenguaje soporta comodines, descenso recursivo, segmentación de arrays y expresiones de filtro, lo suficiente para la mayoría de las necesidades de extracción de datos.

Documento JSON de ejemplo

A lo largo de esta guía, usaremos el siguiente documento JSON como ejemplo de trabajo. Este es el ejemplo clásico de la propuesta original de JSONPath con datos adicionales:

{
  "store": {
    "book": [
      {
        "category": "reference",
        "author": "Nigel Rees",
        "title": "Sayings of the Century",
        "price": 8.95
      },
      {
        "category": "fiction",
        "author": "Evelyn Waugh",
        "title": "Sword of Honour",
        "price": 12.99
      },
      {
        "category": "fiction",
        "author": "Herman Melville",
        "title": "Moby Dick",
        "isbn": "0-553-21311-3",
        "price": 8.99
      },
      {
        "category": "fiction",
        "author": "J.R.R. Tolkien",
        "title": "The Lord of the Rings",
        "isbn": "0-395-19395-8",
        "price": 22.99
      }
    ],
    "bicycle": {
      "color": "red",
      "price": 19.95
    }
  }
}

Referencia de sintaxis JSONPath

JSONPath utiliza un pequeño conjunto de operadores que se combinan para formar consultas potentes. Aquí está la referencia completa de sintaxis:

Expresiones básicas de JSONPath

Acceso al nodo raíz y a los hijos directos

El signo de dólar $ representa el nodo raíz del documento JSON. Desde allí, usas la notación de punto para acceder a las propiedades del objeto y la notación de corchetes para acceder a los índices del array.

Notación de corchetes

La notación de corchetes es una alternativa a la notación de punto, útil cuando los nombres de propiedad contienen caracteres especiales, espacios o comienzan con un número:

$.store['book'][0]['title']
$['store']['bicycle']['color']

La notación de corchetes y la notación de punto son intercambiables para las propiedades del objeto. Sin embargo, la notación de corchetes es obligatoria cuando los nombres de propiedad son dinámicos o contienen caracteres que no son válidos en la notación de punto.

Operador comodín

El operador comodín * coincide con todos los elementos de un array o todas las propiedades de un objeto. Es extremadamente útil para extraer todos los valores en un nivel sin conocer las claves o índices específicos.

Descenso recursivo: el operador de doble punto

El operador de doble punto .. es una de las características más potentes de JSONPath. Busca la clave especificada en cada nivel del árbol JSON, no solo en los hijos directos. Piensa en ello como una búsqueda profunda en todo el documento.

El operador de descenso recursivo es particularmente útil cuando no conoces la ruta exacta hacia los datos deseados, o cuando la misma clave aparece en múltiples niveles de anidamiento. Por ejemplo, si una respuesta de API contiene campos id en varios niveles de anidamiento, $..id recopilaría todos los id.

Segmentación de arrays

La segmentación de arrays te permite seleccionar un rango de elementos de un array. La sintaxis [start:end] selecciona elementos desde el índice de inicio hasta (pero sin incluir) el índice final. Se soportan índices positivos y negativos.

Ten en cuenta que el comportamiento de segmentación puede variar ligeramente entre diferentes implementaciones de JSONPath. La sintaxis anterior sigue las convenciones utilizadas por la mayoría de las bibliotecas populares y el estándar IETF RFC 9535.

Expresiones de filtro

Las expresiones de filtro son donde JSONPath se vuelve realmente potente. Te permiten seleccionar elementos basados en condiciones en lugar de posición. La sintaxis de filtro usa [?(condition)], donde la condición se evalúa para cada elemento.

Operadores de comparación

JSONPath soporta los siguientes operadores de comparación en expresiones de filtro:

Ejemplos prácticos de filtrado

Usando nuestro documento de ejemplo, aquí hay expresiones de filtro prácticas y sus resultados:

Find all books cheaper than $10:

< 10)]

Devuelve los libros "Sayings of the Century" ($8.95) y "Moby Dick" ($8.99).

Find all fiction books:

$.store.book[?(@.category == "fiction")]

Devuelve tres libros: "Sword of Honour", "Moby Dick" y "The Lord of the Rings".

Find books with an ISBN:

$.store.book[?(@.isbn)]

Devuelve los libros que tienen una propiedad isbn: "Moby Dick" y "The Lord of the Rings". Esto se debe a que el filtro verifica la existencia de la propiedad.

Find the most expensive book:

$.store.book[?(@.price > 20)]

Devuelve "The Lord of the Rings" ($22.99).

Operadores lógicos en filtros

Puedes combinar condiciones usando operadores lógicos:

< 10 && @.category == "fiction")]
$.store.book[?(@.price > 15 || @.category == "reference")]

La primera expresión encuentra libros de ficción por debajo de $10 (solo "Moby Dick"). La segunda encuentra libros que cuestan más de $15 o pertenecen a la categoría de referencia (devuelve "Sayings of the Century" y "The Lord of the Rings").

JSONPath vs. XPath

JSONPath está explícitamente modelado según XPath, y los dos lenguajes comparten muchas similitudes conceptuales. Si estás familiarizado con el procesamiento XML, comprender esta relación es útil.

La diferencia clave es que XPath opera sobre un modelo de árbol rico con elementos, atributos, nodos de texto, espacios de nombres e instrucciones de procesamiento. JSONPath opera sobre un modelo más simple de objetos (mapas clave-valor) y arrays (listas ordenadas). Esta simplicidad hace que JSONPath sea más fácil de aprender pero menos expresivo que XPath para consultas complejas.

JSONPath en la práctica

Pruebas de API

JSONPath es indispensable para las pruebas de API. Cuando envías una solicitud a una API y recibes una respuesta JSON grande, JSONPath te permite hacer afirmaciones sobre valores específicos sin navegar manualmente toda la estructura. La mayoría de las herramientas de prueba de API soportan JSONPath de forma nativa.

Por ejemplo, en una prueba podrías verificar que el primer libro cuesta menos de $10:

// Using a JSONPath assertion in testing
response.jsonPath().get("store.book[0].price").should(equals(8.95));

// Find all books by a specific author
response.jsonPath().get("store.book[?(@.author == 'Herman Melville')].title");
// Returns: ["Moby Dick"]

Transformación de datos

Al integrar sistemas que usan diferentes formatos de datos, JSONPath ayuda a extraer y transformar campos específicos. Puedes extraer valores de una estructura JSON y mapearlos a otra sin escribir código de recorrido complejo.

Gestión de configuración

Los archivos de configuración complejos a menudo contienen JSON profundamente anidado. JSONPath te permite consultar valores de configuración específicos sin cargar y analizar toda la estructura. Herramientas como jq usan una sintaxis similar a JSONPath para procesar JSON en tuberías de línea de comandos.

Monitorización y alertas

En sistemas de observabilidad, las consultas JSONPath pueden extraer métricas de logs y respuestas de API en formato JSON. Puedes configurar alertas que se activen cuando una consulta JSONPath devuelva valores que excedan un umbral.

Implementaciones de JSONPath

JSONPath está disponible en prácticamente todos los lenguajes de programación. Aquí están las bibliotecas más populares:

Ejemplo en JavaScript

< 10)]',
  json: data
});
// Returns books with price < 10

Python Example

from jsonpath_ng import parse

data = { /* our sample JSON */ }

# Find all authors
author_expr = parse('$..author')
authors = [match.value for match in author_expr.find(data)]
# ["Nigel Rees", "Evelyn Waugh", "Herman Melville", "J.R.R. Tolkien"]

# Find cheap books
cheap_expr = parse('$.store.book[?(@.price < 10)]')
cheap_books = [match.value for match in cheap_expr.find(data)]

Common Pitfalls and Tips

• Zero-based vs one-based indexing: JSONPath uses zero-based indexing (the first element is [0]), while XPath uses one-based indexing (the first element is [1]). This is a common source of off-by-one errors.
• Implementation differences: Before the IETF standard (RFC 9535), JSONPath implementations varied in their handling of edge cases like empty results, null values, and filter syntax. Always test your expressions with the specific library you are using.
• Filter performance: Recursive descent with filters ($..book[?(@.price < 10)]) can be slow on large documents because it must traverse the entire tree. For performance-critical applications, use more specific paths when possible.
• Case sensitivity: JSONPath is case-sensitive. $.Store will not match $.store. This is consistent with JSON's case-sensitive nature.
• Indexación basada en cero vs. basada en uno: JSONPath usa indexación basada en cero (el primer elemento es [0]), mientras que XPath usa indexación basada en uno (el primer elemento es [1]). Esta es una fuente común de errores por uno.
• Diferencias de implementación: antes del estándar IETF (RFC 9535), las implementaciones de JSONPath variaban en el manejo de casos límite como resultados vacíos, valores null y sintaxis de filtro. Siempre prueba las expresiones con tu biblioteca específica.

Trampas comunes y consejos

En 2024, el IETF publicó el RFC 9535, estandarizando formalmente JSONPath. La especificación resuelve muchas de las ambigüedades e inconsistencias que existían entre implementaciones. Los aspectos clave del estándar incluyen:

• < 10)]) puede ser lento en documentos grandes porque debe recorrer todo el árbol. Para aplicaciones críticas de rendimiento, usa rutas más específicas cuando sea posible.
• Sensibilidad a mayúsculas: JSONPath distingue entre mayúsculas y minúsculas. $.Store no coincidirá con $.store. Esto es consistente con la naturaleza de JSON de distinguir mayúsculas y minúsculas.
• Escape de caracteres especiales: si los nombres de clave contienen puntos o corchetes, debes usar la notación de corchetes con comillas: $['key.with.dots'] en lugar de $.key.with.dots.
• Sin recorrido hacia el padre: a diferencia de XPath, JSONPath no puede navegar al nodo padre. No hay equivalente al .. (eje padre) de XPath. El .. de JSONPath significa descenso recursivo, no padre.

Si estás comenzando un nuevo proyecto, prefiere bibliotecas que implementen el RFC 9535 para máxima compatibilidad y comportamiento predecible.