Guia de consultas JSONPath: Como buscar datos JSON

JSON se ha convertido no lenguaje universal da web. As APIs devolvem JSON, os arquivos de configuração usam JSON e as bases de datos almacenan documentos JSON. Mas a medida que as estruturas JSON se vuelven mais grandes e mais profundamente anidadas, encontrar valores específicos se vuelve cada vez mais difícil. Aquí é onde entra JSONPath. JSONPath é um lenguaje de consulta que te permite navegar e extrair datos de documentos JSON usando expresiones de ruta concisas, tal como XPath lo faz para XML. Esta guia cobre todo, desde a sintaxe básica até o filtrado avanzado, com exemplos práticos que podes aplicar imediatamente.

Que é JSONPath?

JSONPath é um lenguaje de consulta JSON propuesto originalmente por Stefan Goessner em 2007. Proporciona uma sintaxe compacta para seleccionar nodos de documentos JSON, similar a como os selectores CSS apuntan a elementos HTML o as expresiones XPath apuntan a nodos XML. Em vez de escrever bucles e lógica condicional para recorrer estruturas JSON, simplesmente escribes uma expresão que descreve a ruta em direção a os datos desejados.

As expresiones JSONPath começam desde o nodo raíz do documento JSON e navegan através de objetos e arrays até o valor desejado. O lenguaje soporta comodines, descenso recursivo, segmentação de arrays e expresiones de filtro, lo suficiente para a maioria das necessidades de extração de datos.

Documento JSON de exemplo

A lo largo de esta guia, usaremos o seguinte documento JSON como exemplo de trabalho. Este é o exemplo clásico de a propuesta original de JSONPath com 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 sintaxe JSONPath

JSONPath utiliza um pequeno conjunto de operadores que se combinan para formar consultas potentes. Aquí está a referencia completa de sintaxe:

Expresiones básicas de JSONPath

Acesso ao nodo raíz e a os filhos diretos

O signo de dólar $ representa o nodo raíz do documento JSON. Desde ali, usas a notação de ponto para aceder a as propriedades do objeto e a notação de corchetes para aceder a os índices do array.

Notação de corchetes

A notação de corchetes é uma alternativa a a notação de ponto, útil quando os nombres de propriedade contêm caracteres especiais, espaços o começam com um número:

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

A notação de corchetes e a notação de ponto são intercambiaveis para as propriedades do objeto. No entanto, a notação de corchetes é obligatoria quando os nombres de propriedade são dinámicos o contêm caracteres que no são válidos na notação de ponto.

Operador comodín

O operador comodín * coincide com todos os elementos de um array o todas as propriedades de um objeto. É extremadamente útil para extrair todos os valores em um nivel sem conhecer as claves o índices específicos.

Descenso recursivo: o operador de duplo ponto

O operador de duplo ponto .. é uma das características mais potentes de JSONPath. Busca a clave especificada em cada nivel do árbol JSON, no solo nos filhos diretos. Pensa em isso como uma búsqueda profunda em todo o documento.

O operador de descenso recursivo é particularmente útil quando no conheces a ruta exata em direção a os datos desejados, o quando a mesma clave aparece em múltiples niveles de anidamiento. Por exemplo, se uma respuesta de API contém campos id em vários niveles de anidamiento, $..id recopilaria todos os id.

Segmentação de arrays

A segmentação de arrays te permite seleccionar um rango de elementos de um array. A sintaxe [start:end] selecciona elementos desde o índice de inicio até (mas sem incluir) o índice final. Se soportan índices positivos e negativos.

Ten em cuenta que o comportamento de segmentação pode variar ligeramente entre diferentes implementações de JSONPath. A sintaxe anterior segue as convenciones utilizadas por a maioria das bibliotecas populares e o estándar IETF RFC 9535.

Expresiones de filtro

As expresiones de filtro são onde JSONPath se vuelve realmente potente. Te permitem seleccionar elementos basados em condiciones em vez de posição. A sintaxe de filtro usa [?(condition)], onde a condição se evalúa para cada elemento.

Operadores de comparação

JSONPath soporta os seguintes operadores de comparação em expresiones de filtro:

Exemplos práticos de filtrado

Usando nosso documento de exemplo, aquí há expresiones de filtro práticas e suas resultados:

Find all books cheaper than $10:

< 10)]

Devolve os libros "Sayings of the Century" ($8.95) e "Moby Dick" ($8.99).

Find all fiction books:

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

Devolve três libros: "Sword of Honour", "Moby Dick" e "The Lord of the Rings".

Find books with an ISBN:

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

Devolve os libros que têm uma propriedade isbn: "Moby Dick" e "The Lord of the Rings". Isto se deve a que o filtro verifica a existencia de a propriedade.

Find the most expensive book:

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

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

Operadores lógicos em filtros

Podes combinar condiciones usando operadores lógicos:

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

A primera expresão encontra libros de ficção abaixo de $10 (solo "Moby Dick"). A segunda encontra libros que cuestan mais de $15 o pertencem a a categoria de referencia (devolve "Sayings of the Century" e "The Lord of the Rings").

JSONPath vs. XPath

JSONPath está explicitamente modelado segundo XPath, e os dois lenguajes compartilham muitas similitudes conceptuales. Se estás familiarizado com o processamento XML, compreender esta relação é útil.

A diferença clave é que XPath opera sobre um modelo de árbol rico com elementos, atributos, nodos de texto, espaços de nombres e instrucciones de processamento. JSONPath opera sobre um modelo mais simple de objetos (mapas clave-valor) e arrays (listas ordenadas). Esta simplicidade faz que JSONPath seja mais fácil de aprender mas menos expresivo que XPath para consultas complejas.

JSONPath na prática

Experimentas de API

JSONPath é indispensavel para as experimentas de API. Quando envías uma requisição a uma API e recebes uma respuesta JSON grande, JSONPath te permite fazer afirmaciones sobre valores específicos sem navegar manualmente toda a estrutura. A maioria das ferramentas de experimenta de API soportan JSONPath de forma nativa.

Por exemplo, em uma experimenta poderias verificar que o 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"]

Transformação de datos

Ao integrar sistemas que usam diferentes formatos de datos, JSONPath ajuda a extrair e transformar campos específicos. Podes extrair valores de uma estrutura JSON e mapearlos a outra sem escrever código de recorrido complejo.

Gestión de configuração

Os arquivos de configuração complejos frequentemente contêm JSON profundamente anidado. JSONPath te permite consultar valores de configuração específicos sem cargar e analizar toda a estrutura. Ferramentas como jq usam uma sintaxe similar a JSONPath para processar JSON em tuberías de linha de comandos.

Monitorização e alertas

Em sistemas de observabilidade, as consultas JSONPath podem extrair métricas de logs e respuestas de API em formato JSON. Podes configurar alertas que se activen quando uma consulta JSONPath devuelva valores que excedan um umbral.

Implementações de JSONPath

JSONPath está disponivel em praticamente todos os lenguajes de programação. Aquí estão as bibliotecas mais populares:

Exemplo em 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.
• Indexação basada em cero vs. basada em um: JSONPath usa indexação basada em cero (o primer elemento é [0]), enquanto que XPath usa indexação basada em um (o primer elemento é [1]). Esta é uma fuente comum de erros por um.
• Diferenças de implementação: antes do estándar IETF (RFC 9535), as implementações de JSONPath variaban no manejo de casos límite como resultados vazios, valores null e sintaxe de filtro. Siempre experimenta as expresiones com tua biblioteca específica.

Trampas comuns e dicas

Em 2024, o IETF publicó o RFC 9535, estandarizando formalmente JSONPath. A especificação resolve muitas das ambigüedades e inconsistencias que existían entre implementações. Os aspectos clave do estándar incluem:

• < 10)]) pode ser lento em documentos grandes porque deve recorrer todo o árbol. Para aplicaciones críticas de performance, usa rutas mais específicas quando seja possível.
• Sensibilidade a mayúsculas: JSONPath distingue entre mayúsculas e minúsculas. $.Store no coincidirá com $.store. Isto é consistente com a naturaleza de JSON de distinguir mayúsculas e minúsculas.
• Escape de caracteres especiais: se os nombres de clave contêm pontos o corchetes, deves usar a notação de corchetes com comillas: $['key.with.dots'] em vez de $.key.with.dots.
• Sem recorrido em direção a o pai: a diferença de XPath, JSONPath no pode navegar ao nodo pai. No há equivalente ao .. (eje pai) de XPath. O .. de JSONPath significa descenso recursivo, no pai.

Se estás começando um novo projeto, prefere bibliotecas que implementen o RFC 9535 para máxima compatibilidade e comportamento previsível.