- JSON Path é uma linguagem de consulta que pode ser usada para extrair dados de documentos JSON
- Como o OpenAPI é um documento JSON ou YAML, é possível usar JSON Path para realizar várias tarefas no OpenAPI
- Aplicar patches no documento com conteúdo adicional, exemplos de código etc. usando OpenAPI Overlay
- Pode ser usado no Spectral para escrever regras avançadas
- Também pode ser usado no AWS Step Functions
- Como o JSON Path funciona
- Navega e filtra a estrutura de dados JSON e extrai partes específicas
- Sintaxe semelhante à do XPath (usado em XML)
- Exemplo de sintaxe:
$.store.book[?@.price < 10].title
- Uso no OpenAPI
- É possível consultar documentos OpenAPI e extrair partes específicas com o comando
jpp
- Pode ser usado para modificar documentos OpenAPI ou adicionar informações com Overlay
- Atualizar descrições, adicionar informações de contato etc.
- Remover servidores de desenvolvimento/staging da lista de servidores e manter apenas produção
- Adicionar informações de um novo servidor sandbox, entre outras coisas
- Aprendendo mais sobre JSON Path
- Foi padronizado pelo IETF em 2024 (RFC 9535)
- Antes existiam várias variantes, mas a tendência é de unificação com a padronização
- É recomendável seguir a sintaxe da RFC 9535
Opinião do GN⁺
- JSON Path está sendo usado em cada vez mais lugares, então é uma tecnologia útil para conhecer. Em especial, parece que vai se tornar uma habilidade essencial para desenvolvedores e redatores técnicos que lidam com OpenAPI.
- Ainda há alguma confusão porque a sintaxe do JSON Path não está totalmente unificada, mas parece desejável usar a RFC 9535 como referência. Espera-se que as ferramentas relacionadas também passem a seguir esse padrão no futuro.
- Parece haver uma grande variedade de áreas de uso no processo de desenvolvimento, como OpenAPI Overlay e Spectral. O potencial de uso vai além da simples extração de dados, incluindo complementação de documentação, validação e refinamento.
- No entanto, a sintaxe é um pouco complexa e é preciso estar familiarizado com JSON/YAML, então existe uma barreira de entrada. É melhor começar de forma simples e aprender gradualmente os recursos mais avançados.
- Ferramentas de linha de comando como jq e yq parecem boas para praticar. Usar ferramentas integradas como o Bump.sh também deve ajudar na produtividade.
2 comentários
Obrigado
Comentários no Hacker News
JSONata(https://jsonata.org) é uma das melhores ferramentas para manipulação de JSON, usa sintaxe JsonPath e, além da seleção de nós, oferece funções auxiliares para aritmética, comparação, ordenação, agrupamento, manipulação de datas, agregação etc. Foi escrita em JS, pode ser usada no Node ou no navegador, e também tem um wrapper para Python (https://pypi.org/project/pyjsonata/).
json_profile(https://github.com/tylerneylon/json_profile) é uma ferramenta que ajuda a entender rapidamente o esquema principal e a localização dos dados em novos arquivos JSON, sendo útil quando elementos pares de uma lista têm a mesma estrutura. Ela aprende a estrutura do arquivo, imprime os caminhos de agregação mais pesados e fornece dicas de tamanho por caminho.
espath(https://github.com/tomhodgins/espath) é uma biblioteca para filtrar e encontrar dados em JSON usando XPath e seletores CSS. Ela funciona convertendo objetos JavaScript em um XML DOM, executando consultas e depois convertendo de volta em objetos, ou mantendo um registro do objeto original e pesquisando o objeto original.
Houve uma pergunta sobre se existe um nome genérico para a estrutura de dados representada por JSON, além de um comentário sobre a necessidade de uma linguagem de caminhos que funcione em estruturas semelhantes como JSON, YAML, dicionários Python, TOML etc.
O SQLite inclui um subconjunto de JSON Path no banco de dados principal, usado em funções como json_extract(). Nota detalhada relacionada: https://til.simonwillison.net/sqlite/json-extract-path
Insomnia e Bruno têm recursos para filtrar respostas usando JSON Path.
Já foi usado o suporte a jsonpath do PostgreSQL para criar regras personalizadas de filtragem sobre linhas do banco de dados.
Assim como a injeção de XPATH já foi amplamente usada, espera-se que ataques de injeção de caminho JSON sejam inevitáveis. (ver https://owasp.org/www-community/attacks/XPATH_Injection)
É estranho não haver menção a ferramentas semelhantes como jq.
É uma pena existirem sintaxes demais para caminhos JSON. jq, JSON path, AWS CLI, MySQL etc. usam sintaxes diferentes, então é difícil criar memória muscular.