Consultar JSON com JSONPath - As expressoes que voce realmente digita

JSONPath e uma linguagem de consulta para JSON como XPath e para XML: voce aponta para nos em vez de escrever loops aninhados. Na maioria dos dias voce so precisa de alguns tokens - `$`, `@`, pontos, colchetes, `*`, `..`, um slice e um filtro `[?()]` simples. Este guia e essa lista curta, nao um clone completo do RFC. Cole o exemplo abaixo no Testador JSONPath e experimente cada expressao no navegador - nada e enviado.

Um mesmo payload de exemplo

Todos os exemplos usam o documento classico da livraria (o mesmo formato que muitos tutoriais de JSONPath compartilham). Mantenha-o aberto enquanto le:

• `store.book` - um array de objetos com `category`, `author`, `title`, `price` e as vezes `isbn`.
• `store.bicycle` - um objeto aninhado com `color` e `price`.
• Se o payload chegou em uma linha so, formate primeiro com o Minificador e formatador JSON e depois consulte.

$ e @

`$` e a raiz do valor JSON que voce colou - o objeto ou array inteiro. Toda expressao util comeca ali. `@` so faz sentido dentro de um filtro: significa "o elemento atual sendo testado." Fora de um filtro, `@` nao e um cursor livre.

• `$` - a raiz do documento.
• `@.price` dentro de `[?()]` - o campo `price` do item sob teste.
• `$.store.book[?(@.isbn)]` - livros que tem a chave `isbn` (existencia).
• Um caminho sem `$` costuma ser rejeitado por testers estritos - sempre comece com `$`.

Ponto vs colchetes

Notacao com ponto e atalho para identificadores simples: `$.store.book`. Notacao com colchetes e a forma explicita: `$['store']['book']`. Use colchetes quando a chave nao for um identificador simples (espacos, hifens, digitos no inicio) ou quando quiser o estilo de caminho normalizado RFC 9535 que muitas tools mostram na tabela de matches.

• `$.store.bicycle.color` - ok para chaves comuns.
• `$['content-type']` - necessario quando a chave nao e um identificador estilo JS.
• `$['store']['book'][0]['title']` - caminho singular normalizado para um no (estilo RFC 9535 §2.7).
• Indices sempre vao em colchetes: `$.store.book[0]`, nao `$.store.book.0`.

* e ..

`*` e um curinga para "cada filho neste nivel." `..` e descida recursiva: percorre a arvore e coleta matches em qualquer profundidade. Curingas ficam rasos; a descida pode surpreender em documentos grandes.

• `$.store.book[*].title` - o titulo de cada livro (um nivel de itens do array).
• `$.store.*` - tanto `book` quanto `bicycle` sob `store`.
• `$..author` - cada `author` em qualquer lugar sob a raiz.
• `$..price` - precos dos livros e o do bicycle juntos - aperte o caminho se so queria um.

Slices

Slices de array usam `start:end:step` no estilo Python dentro de colchetes. Extremidades omitidas significam "do inicio" ou "ate o fim." Indices negativos contam do fim quando a implementacao os suporta.

• `$.store.book[0:2]` - os dois primeiros livros (indices 0 e 1).
• `$.store.book[-1:]` - o ultimo livro, em engines que permitem indices negativos.
• `$.store.book[::2]` - um livro sim, um nao, quando o step e suportado.
• Slices selecionam itens do array; encadeie um campo depois: `$.store.book[0:2].title`.

Um filtro simples

Filtros ficam em `[?(...)]` e mantem itens onde a expressao e verdadeira. `@` e o elemento atual. Comparacoes em geral nao forcam tipos como JavaScript frouxo - `1 == "1"` costuma ser falso. Mantenha filtros simples: igualdade, desigualdade, compare numerico, `&&`, `||`, `!` e existencia.

• `$.store.book[?(@.price < 10)]` - livros baratos.
• `$.store.book[?(@.price < 10 && @.category == 'fiction')].title` - filtre e depois extraia um campo.
• `$.store.book[?(@.isbn)]` - itens que tem `isbn`.
• Coloque o filtro no array que voce esta varrendo, nao em uma raiz objeto sozinha a menos que a raiz seja um array.

RFC 9535 vs o dialeto Goessner antigo

O artigo de Stefan Goessner de 2007 popularizou JSONPath e muitas bibliotecas ainda copiam seus exemplos. RFC 9535 (2024) e o padrao IETF: gramatica mais clara, caminhos normalizados e menos escapatorias de "eval qualquer coisa". Seletores script como `[(@.length-1)]` e JavaScript livre dentro de filtros pertencem ao velho oeste, nao a um tester seguro no navegador.

• RFC 9535 - operadores padronizados, caminhos normalizados como `$['store']['book'][0]`, feito para implementacoes interoperaveis.
• Amostras da era Goessner - ainda estao em muitos blogs; verifique antes de usar em producao.
• Subconjuntos sem eval - o que voce quer para payloads de API colados. Rejeite seletores script; nunca execute o caminho como JavaScript.
• Quando duas tools discordam, veja qual dialeto reivindicam - nao qual "parece" certo.

Cinco exemplos para copiar e colar

No sample da livraria, experimente estes nesta ordem:

• `$.store.book[*].title` - todos os titulos como lista.
• `$..author` - cada autor via descida recursiva.
• `$.store.book[0:2]` - os dois primeiros objetos livro.
• `$.store.book[?(@.price < 10)]` - livros com preco menor que 10.
• `$.store.book[?(@.price < 10)].title` - o mesmo filtro, so titulos.

Depois de extrair uma lista plana de registros, voce pode querer uma planilha - passe um array JSON de objetos pelo Conversor JSON para CSV. Para blobs de API aninhados que ainda esta explorando, fique no JSONPath ate a forma ficar clara.

Perguntas frequentes

Todo JSONPath comeca com $?

Sim na pratica. `$` nomeia a raiz. Tools estritas rejeitam caminhos que o omitem.

Quando uso @?

So dentro de filtros `[?()]`, como o elemento atual. Nao substitui `$` no inicio de um caminho.

Por que obtive zero matches?

Um caminho valido pode nao bater com nada. Causas comuns: filtrar uma raiz objeto em vez de um array, typo em uma chave, ou esperar coercao de tipos do JavaScript. Tente `$..field` para confirmar que o campo existe e depois aperte.

JSONPath e o mesmo que JMESPath ou jq?

Nao. Ideia relacionada, sintaxe e bibliotecas diferentes. Escolha um dialeto por codebase e fique nele.

Posso testar uma resposta de API privada com seguranca?

Sim se o avaliador roda no navegador sem upload. O Testador JSONPath e feito para isso - cole, consulte, copie JSON extraido ou caminhos normalizados.

Experimente no ToolsMinify

Todas as tools abaixo rodam no navegador - gratis, sem cadastro, sem upload:

• Testador JSONPath - cole JSON, rode uma expressao, copie matches ou valores extraidos.
• Minificador e formatador JSON - formate ou minifique um payload antes de consulta-lo.
• Conversor JSON para CSV - transforme um array JSON plano de objetos em CSV depois de extrair.
• Todas as ferramentas de desenvolvimento - o indice completo da categoria.