Guia de Consultas JSONPath: Extraindo Dados como um Profissional

JSONPath é uma linguagem de consulta para JSON, semelhante ao funcionamento do XPath para XML. Quando você está lidando com respostas de APIs complexas e profundamente aninhadas, o JSONPath permite extrair exatamente os dados que você precisa sem escrever loops e condicionais. Este guia abrange a sintaxe, operadores e padrões do mundo real que você precisa.

Por Que JSONPath?

Considere uma resposta típica de API com dados aninhados:

{
  "store": {
    "books": [
      { "title": "Clean Code", "author": "Robert Martin", "price": 32.99, "tags": ["programming", "best-practices"] },
      { "title": "Design Patterns", "author": "Gang of Four", "price": 44.99, "tags": ["programming", "architecture"] },
      { "title": "The Pragmatic Programmer", "author": "Hunt & Thomas", "price": 39.99, "tags": ["programming", "career"] }
    ],
    "music": [
      { "title": "Kind of Blue", "artist": "Miles Davis", "price": 12.99 }
    ]
  }
}

Para obter todos os títulos de livros, você poderia escrever um loop — ou usar JSONPath: $.store.books[*].title

Sintaxe Básica

Notação de Ponto vs Notação de Colchetes

Ambas as notações acessam propriedades, mas a notação de colchetes é necessária para caracteres especiais:

# Notação de ponto
$.store.books[0].title

# Notação de colchetes (equivalente)
$['store']['books'][0]['title']

# Obrigatório para chaves com caracteres especiais
$['store']['price-range']

Operações com Arrays

Indexação

$.store.books[0]          # Primeiro livro
$.store.books[-1]         # Último livro
$.store.books[0,2]        # Primeiro e terceiro livros

Fatiamento

$.store.books[0:2]        # Dois primeiros livros (índice 0 e 1)
$.store.books[1:]         # Todos os livros exceto o primeiro
$.store.books[:2]         # Dois primeiros livros
$.store.books[::2]        # Um livro sim, um não

Curingas

$.store.books[*].title    # Todos os títulos de livros
$.store.*                 # Todas as coleções da loja (books, music)
$..title                  # Todos os títulos em qualquer profundidade
$..price                  # Todos os preços em qualquer profundidade

O operador de descida recursiva (..) é particularmente poderoso para extrair valores independentemente da posição na hierarquia.

Expressões de Filtro

Filtros selecionam elementos com base em condições:

# Livros mais baratos que $40
$.store.books[?(@.price < 40)]

# Livros de um autor específico
$.store.books[?(@.author == 'Robert Martin')]

# Livros com mais de 2 tags
$.store.books[?(@.tags.length > 2)]

# Livros que têm a propriedade 'price'
$.store.books[?(@.price)]

Combinando Filtros

# Livros abaixo de $40 com tag de programming
$.store.books[?(@.price < 40 && @.tags[0] == 'programming')]

Exemplos do Mundo Real

Extraindo de Respostas de APIs

GitHub API — obter todos os nomes de repositórios:

$[*].name

API de Clima — obter a temperatura de hoje:

$.daily[0].temp.day

API de E-commerce — obter todas as imagens de produtos:

$.products[*].images[0].url

Extração de Configuração

Docker Compose — obter todos os nomes de serviços:

$.services.*~

Package.json — obter todos os nomes de dependências:

$.dependencies.*~

JSONPath vs jq

JSONPath e jq são ambas ferramentas de consulta JSON, mas servem a contextos diferentes:

Para processamento JSON na linha de comando, jq é mais poderoso. Para incorporar consultas em aplicações ou usar em ferramentas web, JSONPath tem suporte mais amplo.

Experimente expressões JSONPath interativamente com nosso Explorador JSON Path. Cole seu JSON, escreva uma consulta e veja os resultados instantaneamente.

Exemplos de Implementação

JavaScript (jsonpath-plus)

const { JSONPath } = require('jsonpath-plus');
const result = JSONPath({
  path: '$.store.books[?(@.price < 40)].title',
  json: data
});
// ["Clean Code", "The Pragmatic Programmer"]

Python (jsonpath-ng)

from jsonpath_ng import parse
expr = parse('$.store.books[*].title')
titles = [match.value for match in expr.find(data)]

RFC 9535: O Padrão JSONPath

Em fevereiro de 2024, o JSONPath foi oficialmente padronizado como RFC 9535. Isso resolve inconsistências históricas entre implementações. Comportamentos padronizados principais:

• Índices de array são base 0
• Expressões de filtro usam @ para o elemento atual
• Comparação de strings diferencia maiúsculas e minúsculas
• O resultado é sempre um array de valores correspondentes

Se você está escolhendo uma biblioteca JSONPath, prefira uma que suporte RFC 9535 para comportamento consistente.

FAQ

Qual é a diferença entre JSONPath e JSON Pointer?

JSONPath é uma linguagem de consulta que pode corresponder a múltiplos valores usando curingas e filtros. JSON Pointer (RFC 6901) é uma sintaxe de caminho simples que endereça exatamente um valor: /store/books/0/title. Use JSONPath quando precisar buscar ou filtrar; use JSON Pointer quando souber o caminho exato.

O JSONPath pode modificar dados JSON?

O JSONPath padrão é somente leitura — ele extrai mas não modifica dados. Algumas bibliotecas estendem o JSONPath com operações de set/delete, mas essas não são padrão. Para transformações, considere jq (linha de comando) ou escreva código na aplicação. Para visualizar e explorar a estrutura JSON, nosso Formatador JSON ajuda você a entender os dados antes de escrever consultas.

Recursos Relacionados

• Explorador JSON Path — Teste expressões JSONPath no seu navegador
• Boas Práticas de Formatação JSON — Estruture seu JSON para consultas mais fáceis
• Guia de Validação JSON Schema — Valide a estrutura que suas consultas JSONPath esperam