Extrator de caminho JSON

Como funciona

1. Cole seu JSON : insira um objeto ou array JSON no campo de entrada.
2. Insira uma expressão JSONPath : digite um caminho como $.store.book[*].author ou $.users[?(@.age > 18)] para selecionar os dados desejados.
3. Visualize os resultados extraídos : os valores correspondentes aparecem instantaneamente no painel de saída. Copie o resultado ou exporte-o.

Por que usar o extrator JSONPath ?

Ao trabalhar com respostas de API complexas ou JSON profundamente aninhado, extrair valores específicos manualmente é lento e sujeito a erros. JSONPath é a linguagem de consulta para JSON, análoga a XPath para XML. Permite segmentar exatamente os dados de que você precisa por meio de uma expressão de caminho concisa, seja um único valor aninhado, todos os elementos de um array ou registros filtrados que correspondam a uma condição. Esta ferramenta torna a exploração JSONPath interativa sem escrever código.

Funcionalidades

• Suporte completo a JSONPath : notação com pontos, notação com colchetes, curingas (*), descida recursiva (..), filtros (?()) e fatias de arrays.
• Avaliação em tempo real : os resultados são atualizados à medida que você digita a expressão JSONPath.
• Saída formatada : os valores extraídos são exibidos como JSON bem formatado.
• Múltiplas correspondências : retorna todos os nós correspondentes do documento JSON.
• Relato de erros : mensagens claras quando a expressão de caminho é inválida ou não produz nenhuma correspondência.

Perguntas frequentes

O que é JSONPath ?

JSONPath é uma linguagem de consulta para documentos JSON, análoga ao XPath para XML. Um caminho como $.users[*].name seleciona o campo name de cada objeto no array users. É amplamente usado para testes de API, transformação de dados e processamento JSON.

Como filtrar elementos de um array por uma condição ?

Use uma expressão de filtro : $.items[?(@.price < 50)] retorna todos os elementos cujo preço é inferior a 50. O símbolo @ refere-se ao elemento em avaliação no momento.

Ele suporta busca recursiva ?

Sim. O operador .. realiza uma busca recursiva em todos os níveis. Por exemplo, $..name encontra todas as chaves name onde quer que estejam na estrutura JSON, independentemente da profundidade de aninhamento.

De um post de blog para RFC 9535: a estrada de 17 anos para um padrão JSONPath

Stefan Gössner propôs JSONPath em um único post de blog em fevereiro de 2007, adaptando a ideia do XPath para JSON. Ele publicou uma implementação JavaScript de referência, esboçou a sintaxe (a raiz $, operadores filho ponto e colchete, .. para descida recursiva, * para coringa, [início:fim:passo] para fatiamento de array, [?(...)] para expressões de filtro) e o ecossistema mais amplo seguiu. As implementações proliferaram: jsonpath para JavaScript, JsonPath para Java, jq (Stephen Dolan, 2012) que é adjacente ao JSONPath mas sua própria coisa, jsonpath-ng para Python, JMESPath (AWS, 2014) como rival mais estrito. O problema: cada implementação divergiu. Sintaxe de filtro, semântica de recursão, correspondência de regex, identificadores de raiz, todos sutilmente diferentes entre bibliotecas. Um estudo comparativo de 2023 por Carsten Bormann et al. testou 41 implementações JSONPath distintas contra a mesma entrada e obteve 41 conjuntos de resultados diferentes para a mesma expressão. O Grupo de Trabalho JSONPath da IETF se reuniu em 2020 para corrigir isso. RFC 9535 «JSONPath: Query Expressions for JSON» foi publicada em fevereiro de 2024, tornando-se o primeiro padrão formal para JSONPath, 17 anos após o post original de Gössner. RFC 9535 codifica a sintaxe, define um formato de saída normalizado, requer normalização Unicode para comparações de string, e adiciona um conjunto de testes de conformidade.

Folha de dicas de sintaxe JSONPath

Os sete operadores que cobrem a maioria das consultas do mundo real:

• $ raiz. Cada caminho começa aqui. $ sozinho retorna o documento inteiro.
• .nome filho por nome. $.store.book seleciona o campo book dentro de store. Nomes com espaços ou caracteres especiais precisam de notação de colchete: $['book title'].
• [0] índice de array. $.book[0] primeiro elemento. $.book[-1] último elemento (adição RFC 9535).
• [início:fim:passo] fatiamento de array. Estilo Python: $.book[1:3] elementos 1 e 2, $.book[::2] cada outro elemento. passo pode ser negativo para reverter.
• * coringa. $.book[*].title o título de cada livro. Também funciona como coringa de propriedade: $.store.* todos os filhos imediatos de store.
• .. descida recursiva. $..title encontra cada campo title em qualquer profundidade. Poderoso mas lento em documentos grandes.
• [?(...)] expressão de filtro. $.book[?(@.price < 10)] todos os livros onde o preço está abaixo de 10. @ significa «o elemento atual». RFC 9535 nomeia isso como ? e padroniza os operadores de comparação == != < <= > >= mais booleanos && ||. O modo rápido deste visualizador não avalia expressões de filtro, use uma biblioteca como jsonpath-plus se precisar delas.

Onde você realmente recorre ao JSONPath

• Filtragem de saída kubectl. kubectl get pods -o jsonpath='{.items[*].metadata.name}' vem no Kubernetes e é um consumidor JSONPath de uso diário. A variante Kubernetes descarta o $ inicial e tem algumas peculiaridades dignas de nota se você vive nesse ecossistema.
• Testes de API com Postman ou Insomnia. Asserções de teste como pm.expect(jsonData.items[0].status).to.eql('active') são geralmente expressas como JSONPath por baixo dos panos.
• Dashboards Grafana / observabilidade. Painéis de fonte de dados JSON consultam métricas usando JSONPath; coletores OpenTelemetry usam uma sintaxe semelhante a JSONPath para extrair atributos de span.
• Extração CLI rápida. Combine esta ferramenta com curl | jq para exploração de API ao vivo: prototipe o caminho no visualizador, depois traduza para sintaxe jq para scripts shell. (jq usa notação de ponto mas não é estritamente JSONPath.)
• ETL e engenharia de dados. Mapeamentos Airflow XCom, arquivos seed dbt, e extração de colunas JSON SQL usam expressões semelhantes a JSONPath para alcançar payloads aninhados.
• Inspeção de tokens. Aprofunde em um JWT decodificado: $.payload.iss para o emissor, $..roles[*] para cada papel concedido em qualquer lugar na árvore de reivindicações.
• Design de manipulador webhook. Antes de escrever o código do manipulador, cole um payload webhook real e prototipe os caminhos que extraem os campos que importam para seu sistema. Economiza uma ida e volta com o serviço upstream.

Erros que mordem

• Divergência de implementação. Um caminho que funciona em uma biblioteca pode produzir resultados diferentes, ou nenhum resultado, em outra. Antes da RFC 9535 nada era padronizado. Agora procure «conforme RFC 9535» na doc da sua biblioteca (o conjunto de testes IETF é publicado com a RFC).
• Aspas de filtro. $.book[?(@.title=="Foo")] requer aspas duplas dentro do filtro em RFC 9535; muitas bibliotecas mais antigas aceitam aspas simples 'Foo' também. Misturá-las é uma causa comum de «erro de sintaxe» em produção.
• A descida recursiva é gananciosa. $..* retorna cada valor no documento, incluindo objetos e arrays aninhados eles mesmos, não apenas folhas. Em documentos grandes isso pode levar segundos. Estreite o caminho primeiro, depois desça.
• Chaves inteiras vs string. JSON só tem chaves de string, mesmo quando elas parecem numéricas. $.users.123 e $.users[123] significam coisas diferentes em algumas bibliotecas: a primeira procura uma propriedade literalmente chamada "123", a segunda pode ser interpretada como índice de array 123.
• Fatias negativas. $.book[-1:] significa «o último elemento» em RFC 9535 e na maioria das implementações, mas antes de 2024 algumas bibliotecas tratavam índices negativos como erros. Se você visa parsers mais antigos, use índices absolutos.
• Esquecer $. Um caminho sem $ inicial é inválido em RFC 9535. Algumas implementações aceitam .store.book como atalho, outras o rejeitam. Sempre prefixe com $.
• Desempenho. A descida recursiva .. em um documento de 10 MB pode ser O(n) por correspondência. Para colunas de data warehouse ou loops quentes, pré-extraia uma vez com $.., cache o resultado, depois percorra o array cacheado. Nunca execute um JSONPath complexo a cada requisição.

JSONPath vs jq vs JMESPath vs JSON Pointer

• JSONPath (RFC 9535). Melhor para consultas ad-hoc e arquivos de configuração. A sintaxe é familiar do XPath, o padrão é fresco, múltiplas bibliotecas de linguagem o suportam.
• jq. Uma linguagem completa de transformação de dados, não apenas uma consulta de caminho. Adiciona map/filter/reduce, funções de string, matemática, formatação. Melhor quando você precisa remodelar dados, não apenas extraí-los. Tem sua própria sintaxe com notação de ponto mas diverge do JSONPath no nível de filtro.
• JMESPath. Uma alternativa de 2014 usada pelo AWS CLI (aws ec2 describe-instances --query "..."). Mais estrito e funcional que JSONPath, tem uma gramática real desde o primeiro dia, suporta projeções e operadores pipe. Menos comum fora do ecossistema da Amazon.
• JSON Pointer (RFC 6901). Um padrão de 2013 para endereçar um único valor: /store/book/0/title. Não pode fazer coringas, filtros, ou recursão. Usado por JSON Patch (RFC 6902), JSON Schema $ref, e a API de patch do Kubernetes. Escolha isso quando precisar de apontamento exato, não consulta.

Mais perguntas frequentes

JSONPath é o mesmo que XPath?

Inspirado por ele, não idêntico. XPath foi finalizado pela W3C em 1999 para XML, JSONPath foi esboçado por Gössner em 2007 para trazer a mesma ideia para JSON. As maiores diferenças: JSONPath usa . e [] em vez de /, JSONPath não tem conceito de namespaces ou atributos XML, JSONPath foi padronizado muito depois (2024 vs 1999), então por anos foi uma sintaxe de facto com muitas implementações incompatíveis.

Por que o mesmo JSONPath dá resultados diferentes em ferramentas diferentes?

Porque JSONPath não foi padronizado até a RFC 9535 (fevereiro de 2024). Antes disso, cada implementação fazia suas próprias escolhas sobre sintaxe de filtro, suporte a regex, identificadores de raiz, regras de escape, e casos limites (arrays vazios, chaves faltantes, coerção de tipo em filtros). Um estudo do grupo de trabalho IETF de 2023 testou 41 implementações na mesma entrada e obteve 41 conjuntos de resultados diferentes. RFC 9535 conserta isso para bibliotecas novas e atualizadas; bibliotecas mais antigas divergirão até migrarem. Sempre verifique se sua biblioteca afirma «conformidade RFC 9535».

Posso modificar o JSON com JSONPath, ou apenas ler?

RFC 9535 define JSONPath estritamente como uma linguagem de consulta: ela retorna valores de um documento, ela não muta. Para modificar JSON, use JSON Patch (RFC 6902), que usa caminhos JSON Pointer e operações add/remove/replace/copy/move/test. Algumas bibliotecas combinam ambas (e.g. jsonpath-plus em JavaScript tem uma extensão de mutação apply()) mas isso não é JSONPath padrão.

JSONPath suporta expressões regulares em filtros?

RFC 9535 adicionou duas funções regex: match(node, regex) corresponde à string inteira, search(node, regex) corresponde a qualquer substring. Exemplo: $.book[?(match(@.isbn, "^978-"))]. O sabor regex é I-Regexp (RFC 9485, um perfil de regex de XML Schema), não PCRE ou regex JavaScript. Bibliotecas mais antigas usavam o sabor regex da linguagem host, o que torna consultas regex especialmente não portáveis.

Meu JSON é enviado para algum lugar quando uso esta ferramenta?

Não. A avaliação de caminho executa inteiramente no motor JavaScript do seu navegador. Abra a aba Rede em DevTools e execute uma consulta, você verá zero requisições de saída durante a avaliação. Seguro para respostas API com segredos, dumps de banco de dados com PII, ou arquivos de configuração contendo credenciais.