JSONPath é uma linguagem de consulta para extrair valores de um documento JSON por caminho — o mesmo papel que o XPath cumpre para XML, algo familiar para quem trabalhou com sistemas públicos ou bancários em Portugal e no Brasil que ainda usam XML/SOAP em integrações legadas.
Sintaxe básica
Uma expressão sempre começa com $, a raiz do documento. A partir daí, os campos são acessados com ponto ($.user.name) ou colchetes ($['user']['name']), e elementos de array por índice ($.items[0]).
Selecionando vários valores de uma vez
O curinga * seleciona todos os elementos de um nível, enquanto .. é descida recursiva — encontra um campo em qualquer profundidade sem precisar do caminho exato. Filtros como [?(@.price < 10)] selecionam elementos de array por uma condição parecida com uma expressão de programação.
Para que isso serve
- Extrair rapidamente um campo de uma resposta grande de API durante depuração, sem escrever um script.
- Filtrar logs ou eventos em JSON por uma condição na hora.
- Ler um valor de um arquivo de configuração sem escrever um parser manualmente.
JSONPath vs. XPath: o erro de indexação clássico
Quem vem do XPath, onde a indexação de nós começa em 1 (book[1] é o primeiro elemento), costuma errar ao usar JSONPath, onde a indexação começa em 0 — book[1] já é o segundo elemento. Essa diferença sozinha explica boa parte dos bugs ao migrar integrações antigas de XML/XPath para APIs JSON.
Chaves com pontos ou espaços
Se o nome de um campo contém ponto, hífen ou espaço (por exemplo, uma chave literal "user.name", e não campos aninhados), a notação de ponto $.user.name fica ambígua — o parser interpreta como os campos aninhados user e name. Nesse caso, a chave precisa ir entre colchetes com aspas: $['user.name'].