Guia de Consulta JSONPath: Extraia Precisamente Dados Aninhados do JSON

O que é JSONPath

JSONPath é uma linguagem de consulta para JSON, semelhante ao XPath para XML, que extrai dados com precisão de JSON aninhado complexo:

{
  "store": {
    "books": [
      {"title": "The Three-Body Problem", "price": 68},
      {"title": "To Live", "price": 45},
      {"title": "One Hundred Years of Solitude", "price": 55}
    ]
  }
}

Use $.store.books[*].title para extrair todos os títulos: ["The Three-Body Problem", "To Live", "One Hundred Years of Solitude"]

Referência de Sintaxe Básica

Sintaxe	Significado	Exemplo
`$`	Nó raiz	`$`
`.`	Nó filho	`$.store`
`[]`	Índice de array ou nó filho	`$[0]`, `$['key']`
`*`	Curinga, todos os elementos	`$.store.*`
`..`	Descida recursiva, todos os níveis	`$..title`
`[start:end]`	Slice de array	`$[0:2]`
`[?(expr)]`	Expressão de filtro	`$[?(@.price > 50)]`

Sintaxe Explicada em Detalhes

Nó Raiz $

$ representa a raiz do JSON. Todos os caminhos começam a partir de $:

$           → Todo o JSON
$.store     → O objeto store

Acesso a Nó Filho .

Use . ou [] para acessar nós filhos:

$.store.books        → O array books
$.store['books']     → Forma equivalente; necessária quando nomes de chaves contêm caracteres especiais

Índice de Array []

$.store.books[0]     → Primeiro livro
$.store.books[-1]    → Último livro
$.store.books[0:2]   → Primeiros dois livros (slice)

Curinga *

$.store.books[*]           → Todos os livros
$.store.books[*].title     → Todos os títulos

Descida Recursiva ..

.. busca em todos os níveis sem precisar do caminho completo:

$..title     → Todos os campos title em qualquer nível
$..price     → Todos os campos price em qualquer nível

.. é especialmente útil em respostas de API profundamente aninhadas.

Expressões de Filtro ?()

A filtragem é o recurso mais poderoso do JSONPath:

Operadores de Comparação

Operador	Significado	Exemplo
`==`	Igual a	`$[?(@.price == 45)]`
`!=`	Diferente de	`$[?(@.price != 45)]`
`>`	Maior que	`$[?(@.price > 50)]`
`<`	Menor que	`$[?(@.price < 50)]`
`>=`	Maior ou igual a	`$[?(@.price >= 55)]`

Operadores Lógicos

$[?(@.price > 50 && @.price < 70)]    → Preço entre 50 e 70
$[?(@.category == 'fiction' || @.price < 40)]    → Ficção ou preço abaixo de 40

Correspondência de Strings

$[?(@.title =~ /Three.*/)]    → Título começando com "Three"

Usando a Ferramenta JSONPath

Passo 1: Abrir a Ferramenta

Visite a ferramenta JSONPath para acessar a interface de consulta.

Passo 2: Inserir Dados JSON

Cole sua resposta de API ou dados JSON na caixa de entrada. Você pode embelezá-los primeiro com o Formatador JSON.

Passo 3: Escrever uma Expressão JSONPath

Insira uma expressão na caixa de consulta, ex.: $.data.users[*].name.

Passo 4: Visualizar Resultados da Extração

A ferramenta exibe os resultados correspondentes em tempo real e destaca os nós correspondidos na origem.

Prática: Extraindo Dados de Respostas de API

Exemplo de API do GitHub

{
  "items": [
    {"full_name": "vuejs/vue", "stargazers_count": 45000, "language": "TypeScript"},
    {"full_name": "facebook/react", "stargazers_count": 42000, "language": "JavaScript"}
  ]
}

$.items[*].full_name              → Todos os nomes de repositórios
$.items[?(@.stargazers_count > 43000)].full_name  → Nomes de repos com Stars > 43000

Extração de Dados Paginados

$.data.list[*].id                 → Todos os IDs na página atual
$.pagination.next_cursor          → Cursor da próxima página

JSONPath vs JMESPath

Comparação	JSONPath	JMESPath
Estilo de sintaxe	Similar ao XPath	Similar ao SQL/pipes
Busca recursiva	`..` suportado nativamente	Requer travessia explícita
Sintaxe de filtro	`[?(@.x > 1)]`	`[?x >` 1`]`
Projeção/transformação	Não suportado	Suporta `[*].{n: name}`
Ordenação de múltiplos resultados	Não garantida	Pode ordenar
Ferramenta	JSONPath	JMESPath

Use JSONPath para extração simples, JMESPath para transformação/projeção.

Problemas Comuns

Problema	Causa	Solução
Consulta retorna vazio	Erro de digitação no caminho	Verificar maiúsculas/minúsculas dos nomes de chaves
Filtro não funciona	Diferença na versão da sintaxe	Confirmar a versão de sintaxe suportada pela ferramenta
Índice do array fora dos limites	Índice excede o intervalo	Usar `[*]` ou verificar o comprimento do array
Muitos resultados recursivos	`..` correspondeu a todos os níveis	Reduzir o escopo ou adicionar condições de filtro
Erro em chave com caracteres especiais	Chave contém `.` ou `-`	Usar sintaxe de colchetes `['key.name']`

Resumo

JSONPath é uma ferramenta poderosa para trabalhar com dados JSON. Domine os seis elementos de sintaxe principais — $, ., [], *, .., ?() — e você poderá extrair dados com precisão de qualquer JSON aninhado. A ferramenta JSONPath fornece consultas em tempo real com destaque de posicionamento, enquanto o JMESPath e o Formatador JSON completam seu fluxo de trabalho de processamento de dados JSON.