Como testar uma expressão JSONPath em dados JSON

Para que serve

O JSON Path Tester permite consultar texto em formato JSON através de uma expressão de caminho. É útil quando precisa de localizar propriedades de objetos, percorrer valores dentro de objetos ou itens de listas e selecionar posições específicas sem analisar manualmente toda a estrutura.

O ponto de partida é um documento JSON e um caminho compatível com as formas suportadas pela ferramenta. O caminho pode usar propriedades separadas por pontos, um carácter curinga para atravessar valores de objetos ou itens de listas e expressões entre parênteses retos para índices ou intervalos de índices de listas. A consulta devolve os valores encontrados quando a extração termina normalmente.

A entrada JSON e o caminho são campos de texto opcionais. Se um deles estiver vazio ou contiver apenas espaços, a ferramenta termina com sucesso, mas sem correspondências. Esta condição é diferente de uma consulta válida que simplesmente não encontra o caminho indicado.

Como fazer a consulta

1. Prepare o conteúdo JSON como texto. Por exemplo, pode usar uma estrutura com dados de clientes, produtos ou tarefas. Confirme que as aspas, chavetas, parênteses retos e vírgulas formam um JSON válido.

2. Introduza esse texto no campo de entrada JSON. Se deixar o campo vazio ou escrever apenas espaços, a operação será concluída sem correspondências, por isso essa opção não serve para testar uma estrutura.

3. Escreva a expressão de caminho no campo correspondente. Para propriedades aninhadas, use segmentos separados por pontos, como cliente.nome. Para atravessar valores de objetos ou itens de listas, use o carácter curinga suportado. Para selecionar posições de uma lista, use a notação entre parênteses retos; também pode indicar um intervalo de índices quando a expressão estiver nessa forma suportada.

4. Execute a consulta. Com JSON válido e um caminho que termine normalmente, verifique os valores encontrados, a quantidade de valores e o caminho fornecido. Se não existir um valor nesse caminho, o resultado continua a ser uma operação bem-sucedida, mas sem correspondências.

5. Se a entrada e o caminho contiverem texto não vazio, reveja a sintaxe quando o JSON for inválido: nesse caso, a operação produz um resultado de insucesso em vez de uma extração bem-sucedida. Se o problema estiver no caminho, corrija primeiro índices, intervalos e parênteses retos. Algumas expressões malformadas podem não apresentar a estrutura normal do resultado, pelo que deve preferir formas de caminho suportadas.

Como interpretar o resultado

Leia o resultado em três partes: os valores encontrados, o número de correspondências e o caminho que foi fornecido. Uma contagem igual a zero pode significar que o JSON é válido, mas não contém a propriedade, posição ou percurso pedido; não indica, por si só, que o documento seja inválido.

Distinga esse caso de uma falha causada por JSON inválido. A regra depende do conteúdo dos dois campos: quando o JSON e o caminho têm texto não vazio, um JSON inválido não produz uma extração bem-sucedida. Já uma entrada vazia ou composta apenas por espaços, ou um caminho nessas condições, é tratado primeiro e termina sem correspondências.

A ferramenta não deve ser tratada como compatível com todas as variantes de JSONPath. Use apenas as formas verificadas: propriedades separadas por pontos, curinga para percorrer valores ou itens e índices ou intervalos de listas entre parênteses retos. Uma expressão malformada pode não devolver o formato normal do resultado, sobretudo quando contém índices ou intervalos incorretos.

Exemplo prático

Uma pessoa quer confirmar que consegue localizar o nome dentro de um objeto JSON aninhado.

Introduza o JSON {"cliente":{"nome":"Ana"}}, escreva cliente.nome como caminho e execute a consulta.

O resultado bem-sucedido apresenta os valores encontrados em cliente.nome, o número de valores encontrados e o caminho fornecido.

Limitações

• A ferramenta cobre apenas as formas de caminho verificadas. Expressões malformadas, incluindo certos índices ou intervalos incorretos, podem não devolver a estrutura normal do resultado.

Erros comuns

• Um erro frequente é alterar o caminho quando o problema está no JSON, ou introduzir índices e intervalos malformados. Valide a estrutura JSON e substitua a expressão por uma forma suportada, usando propriedades com pontos ou índices e intervalos corretamente delimitados.

Perguntas frequentes

O que acontece se não preencher o caminho?

Se o caminho estiver vazio ou contiver apenas espaços, a ferramenta termina com sucesso, mas sem correspondências. Para obter valores, introduza uma expressão de caminho não vazia.

Como é tratado um JSON inválido?

Se o JSON e o caminho tiverem texto não vazio, um JSON inválido produz um resultado de insucesso. Se a entrada JSON estiver vazia ou contiver apenas espaços, essa condição é tratada primeiro e termina sem correspondências.

Que formas de caminho posso utilizar?

Use propriedades separadas por pontos, o carácter curinga suportado e expressões entre parênteses retos para índices ou intervalos de listas. A ferramenta não fica, por isso, definida como compatível com todas as expressões JSONPath.