Guia de Consultas JSONPath: Extrair Dados como um Profissional

O JSONPath é uma linguagem de consulta para JSON, semelhante à forma como o XPath funciona para XML. Quando está a lidar com respostas JSON complexas e profundamente aninhadas de APIs, o JSONPath permite-lhe extrair exatamente os dados de que necessita sem escrever ciclos e condicionais. Este guia abrange a sintaxe, os operadores e os padrões do mundo real de que precisa.

Porquê 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 dos livros, poderia escrever um ciclo — ou utilizar JSONPath: $.store.books[*].title

Sintaxe Básica

Notação de Ponto vs Notação de Parênteses

Ambas as notações acedem a propriedades, mas a notação de parênteses é necessária para caracteres especiais:

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

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

# Necessária 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]        # Primeiros dois livros (índice 0 e 1)
$.store.books[1:]         # Todos os livros exceto o primeiro
$.store.books[:2]         # Primeiros dois livros
$.store.books[::2]        # Um livro sim, um livro não

Wildcards

$.store.books[*].title    # Todos os títulos dos 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 sua posição na hierarquia.

Expressões de Filtro

Os filtros selecionam elementos com base em condições:

# Livros com preço inferior a $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 uma propriedade 'price'
$.store.books[?(@.price)]

Combinar Filtros

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

Exemplos do Mundo Real

Extrair de Respostas de API

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

$[*].name

API de Meteorologia — 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

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

Para processamento JSON na linha de comandos, o jq é mais poderoso. Para incorporar consultas em aplicações ou utilizar em ferramentas web, o JSONPath é mais amplamente suportado.

Experimente expressões JSONPath interativamente com o nosso Explorador JSON Path. Cole o 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. Isto resolve inconsistências históricas entre implementações. Comportamentos padronizados principais:

• Os índices de arrays são baseados em 0
• As expressões de filtro utilizam @ para o elemento atual
• A comparação de strings é sensível a maiúsculas e minúsculas
• O resultado é sempre um array de valores correspondentes

Se está a escolher uma biblioteca JSONPath, prefira uma que suporte RFC 9535 para um comportamento consistente.

FAQ

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

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

O JSONPath pode modificar dados JSON?

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

Recursos Relacionados

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