Neste artigo
O que é JSONPath?
JSONPath é uma linguagem de consulta para extrair dados de documentos JSON. Assim como o XPath navega em documentos XML, o JSONPath navega em estruturas JSON usando uma sintaxe de expressão concisa. Foi formalizado no RFC 9535 (fevereiro de 2024) após anos de especificação informal.
As expressões JSONPath começam com $ (o elemento raiz) e usam notação de ponto ou de colchetes para percorrer o documento. A linguagem suporta curingas, descida recursiva, fatiamento de arrays e expressões de filtro — tornando possível extrair valores profundamente aninhados com uma única expressão.
Sintaxe JSONPath
O JSONPath fornece vários operadores para navegar e filtrar estruturas JSON.
- Raiz ($) — toda expressão JSONPath começa com $ representando o objeto ou array raiz do documento JSON
- Notação de ponto ($.store.book) — acessa propriedades filhas por nome, semelhante ao acesso a objetos em JavaScript. Os pontos separam cada nível de aninhamento.
- Notação de colchetes ($['store']['book']) — sintaxe alternativa que usa nomes de propriedade entre aspas em colchetes. Necessária quando os nomes de propriedade contêm caracteres especiais ou espaços.
- Curinga (*) — corresponde a todos os elementos no nível atual. $.store.* retorna todos os filhos diretos de store; $[*] retorna todos os elementos de um array raiz.
- Descida recursiva (..) — pesquisa todos os descendentes em qualquer profundidade. $..price encontra cada campo 'price' em qualquer parte do documento, independentemente do nível de aninhamento.
- Fatias de array ([início:fim:passo]) — seleciona um intervalo de elementos do array. $[0:3] retorna os primeiros três elementos; $[-2:] retorna os dois últimos; $[::2] retorna cada dois elementos.
Exemplos de expressões JSONPath
Aqui estão exemplos práticos mostrando como as expressões JSONPath extraem dados de estruturas JSON reais.
- Extração de valores aninhados — $.users[0].name recupera o nome do primeiro usuário. $.config.database.host obtém um valor de configuração profundamente aninhado.
- Filtragem de arrays — $.users[?(@.age > 18)] retorna todos os usuários com mais de 18 anos. $.products[?(@.price < 50)] encontra produtos acessíveis. Os filtros usam @ para referenciar o elemento atual.
- Consultas em múltiplos níveis — $..author retorna cada campo de autor em qualquer profundidade. $.store.book[*].title retorna todos os títulos de livros. $.orders[*].items[*].sku extrai SKUs de todos os pedidos e itens.
Essas expressões podem ser combinadas para criar consultas poderosas. Por exemplo, $.store.book[?(@.price < 10)].title retorna títulos de todos os livros com preço inferior a 10.
Experimente gratuitamente — sem cadastro
Testar expressoes JSONPath →Casos de uso comuns
O JSONPath é usado onde dados estruturados precisam ser consultados ou extraídos de documentos JSON.
- Extração de respostas de API — extraia campos específicos de respostas de API complexas sem escrever código de análise personalizado. Teste expressões com respostas de amostra antes de codificar.
- Análise de configuração — extraia valores de arquivos de configuração JSON em pipelines CI/CD, scripts de implantação e ferramentas de infraestrutura como código
- Análise de logs — consulte logs JSON estruturados para encontrar eventos específicos, padrões de erros ou métricas de desempenho em arquivos de log grandes
- Transformação de dados — use JSONPath em pipelines ETL para selecionar, filtrar e reformatar dados JSON durante operações de importação/exportação
JSONPath vs JQ vs JMESPath
Várias linguagens de consulta têm como alvo documentos JSON. Cada uma tem pontos fortes diferentes e suporte de ecossistema.
- JSONPath — sintaxe de consulta padrão (RFC 9535), amplamente suportada em bibliotecas de programação (Java, Python, JavaScript, PHP). Ideal para extração e filtragem simples. Sem transformação integrada.
- JQ — processador JSON de linha de comando com uma linguagem funcional poderosa. Suporta transformação, computação e formatação de saída. Ideal para scripts de shell e processamento de dados na linha de comando.
- JMESPath — linguagem de consulta usada pelo AWS CLI e Boto3. Sintaxe mais rígida que o JSONPath com funções embutidas. Ideal para integração com o ecossistema AWS e consultas programáticas.
Perguntas frequentes
O JSONPath usa indexação de array baseada em zero ou em um?
O JSONPath usa indexação de array baseada em zero, consistente com a maioria das linguagens de programação. $[0] retorna o primeiro elemento, $[1] retorna o segundo, e assim por diante. Índices negativos contam a partir do final: $[-1] retorna o último elemento, $[-2] retorna o penúltimo.
Como funcionam as expressões de filtro no JSONPath?
As expressões de filtro usam a sintaxe [?(expressão)] onde @ se refere ao elemento atual sendo avaliado. Você pode usar operadores de comparação (==, !=, <, >, <=, >=), operadores lógicos (&& e ||) e acesso a propriedades (por exemplo, @.name). Exemplo: $[?(@.status == 'active')] retorna elementos onde status é igual a 'active'.
Todas as implementações de JSONPath são compatíveis?
Não completamente. Antes do RFC 9535 (2024), o JSONPath não tinha um padrão formal e as implementações variavam. As diferenças comuns incluem a sintaxe de expressões de filtro, o comportamento da descida recursiva e o tratamento de propriedades ausentes. O RFC 9535 visa padronizar o comportamento, mas bibliotecas mais antigas podem ainda seguir convenções diferentes. Sempre teste as expressões com sua implementação específica.