Consulta JSONPath

O que é um testador de JSONPath?#

Quando um documento JSON é pequeno, lê-se com os olhos. Quando tem alguns milhares de linhas — uma resposta de API, um despejo de configuração, uma árvore de dependências — os olhos deixam de ser a ferramenta certa. JSONPath é a linguagem de consulta para essa situação: uma expressão compacta que diz “dê-me todos os campos price”, ou “os títulos dos livros mais baratos que 10”, ou “todos os nós chamados isbn não importa quão fundo estejam enterrados”.

Pense nisto como um cruzamento entre um caminho de arquivo e uma pequena linguagem de filtragem. $.store.book[0].title desce por uma estrutura conhecida como um caminho de sistema de arquivos. $..author diz “desça recursivamente e recolha todos os author que encontrar”. [?(@.price < 10)] é um filtro: manter apenas os elementos em que o price do nó atual é inferior a dez. O @ significa sempre “o nó que estou atualmente a observar”.

Esta página executa uma expressão JSONPath contra o seu JSON, lista todas as correspondências e — a parte que mais tempo poupa — destaca os intervalos correspondentes diretamente no documento formatado, para que num relance veja se a sua expressão selecionou o que pensa ter selecionado. Os filtros são avaliados com um analisador de expressões seguro, nunca executando código, pelo que um blob não fiável não consegue executar nada.

Como usar#

1. Cole o seu JSON no painel Entrada à esquerda, ou clique em Exemplo para carregar a clássica fixture da livraria.
2. Escreva uma expressão JSONPath no campo JSONPath à direita. Pontos de partida comuns:
   • $.store.book[*].author — o author de todos os elementos do array.
   • $..author — descida recursiva: todos os author, em qualquer lado.
   • $.store.book[?(@.price < 10)].title — uma expressão de filtro.
   • $.store.book[?(@.isbn)].isbn — um teste de existência (tem chave isbn).
3. A lista de correspondências por baixo do campo preenche-se com uma entrada por resultado, e a pré-visualização JSON de largura total por baixo destaca cada intervalo correspondente no sítio.
4. O cabeçalho ao lado de Correspondências mostra a contagem. Uma expressão que corresponda a zero nós ainda reporta sucesso (lista vazia) — só uma expressão sintaticamente inválida mostra erro.
5. Clique em Copiar correspondências na barra de ferramentas para recolher os valores correspondentes como um array JSON, ou Limpar para repor ambos os painéis.

As consultas disparam à medida que escreve. Se o próprio JSON for inválido, a barra de estado aponta para a linha e coluna exatas a corrigir.

Principais funcionalidades#

• Destaque no sítio. Cada valor correspondente é sobreposto ao documento formatado, pelo que um $.. recursivo que agarra trinta nós é instantaneamente visível em vez de enterrado numa lista.
• Avaliação de filtros segura. Expressões como [?(@.price < 10)] são analisadas por um avaliador de expressões, não entregues a execução dinâmica de código — a página mantém-se segura para CSP mesmo com entrada hostil.
• “Sem correspondência” vs “erro” distintos. Uma expressão válida que não selecione nada é reportada como zero correspondências; só uma expressão malformada é sinalizada como erro. Nunca confunde “nada encontrado” com “partiu”.
• Ponteiro por correspondência. Cada resultado transporta o seu JSON Pointer (por exemplo /store/book/2/title), pelo que sabe exatamente de onde na árvore veio um valor.
• Copiar como array. Os valores correspondentes são exportados como um array JSON limpo, pronto a encadear no passo seguinte.
• Apenas local. Os seus dados são consultados no navegador. Não há backend nem envio.

Exemplo prático#

Carregue em Exemplo, depois execute um filtro que encontre os títulos dos livros baratos. Introduza isto no campo JSONPath:

$.store.book[?(@.price < 10)].title

A lista de correspondências devolve dois títulos, porque apenas dois dos quatro livros na fixture têm preço inferior a 10:

[
  "Sayings of the Century",
  "Moby Dick"
]

A pré-visualização JSON destaca esses dois valores de title no sítio, e consegue ver porque é que os outros dois foram excluídos — Sword of Honour (12.99) e The Lord of the Rings (22.99) ficam acima do limiar. Mude para um teste de existência para descobrir que livros têm ISBN:

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

Isto devolve as duas strings ISBN e nada mais, porque o filtro mantém apenas os elementos que efetivamente têm uma chave isbn — um padrão útil para descobrir “que registros têm um campo em falta” negando-o.

FAQ#

Qual é a diferença entre $ e @?#

$ é a raiz do documento — o valor JSON inteiro que colou. @ é o nó atual a ser considerado dentro de um filtro. Por isso em [?(@.price < 10)], o @ refere-se a qualquer livro que o filtro esteja testando agora; escrever $.price aí saltaria de volta à raiz e procuraria um price de topo que não existe.

A minha expressão não corresponde a nada. Isso é um bug?#

Provavelmente não. Uma expressão válida que seleciona zero nós é uma consulta bem-sucedida com resultado vazio — por exemplo, $.store.book[?(@.price > 1000)] no exemplo significa simplesmente que nenhum livro é tão caro. O cabeçalho mostra “0 correspondências” sem erro. Só quando a expressão em si não é analisável é que a página reporta erro.

Porque é que um filtro não executa JavaScript arbitrário?#

Os filtros são avaliados por um analisador de expressões dedicado que compreende comparações, operadores booleanos e referências @ — nunca constrói nem executa código. Isto é deliberado: mantém a ferramenta segura de apontar a JSON em que não confia totalmente, e mantém a página dentro da política de segurança de conteúdos do navegador.

O JSONPath consegue editar ou remover nós?#

Não — isto é uma ferramenta de consulta só de leitura. Seleciona e exibe, não muta o seu JSON. Se em vez disso quiser ver como dois documentos diferem, recorra à ferramenta /en/json/diff/.