Um caminho até um valor do documento
Um ponteiro JSON, ou JSON Pointer, é uma string que identifica um valor específico dentro de um documento JSON. A avaliação parte da raiz do documento e percorre os segmentos separados por / até chegar ao valor indicado.
Cada segmento seleciona uma propriedade pelo nome quando o valor atual é um objeto. Quando o valor é um array, o segmento indica a posição do elemento, começando em zero. A RFC 6901 define essa sintaxe para identificar valores específicos, sem executar buscas por filtros ou criar propriedades ausentes.
Da lista de usuários ao nome
Neste documento de exemplo, a propriedade usuarios contém um array com um objeto:
{ "usuarios": [ { "nome": "Ana" } ]}O ponteiro /usuarios/0/nome seleciona o array usuarios, acessa seu primeiro elemento pelo índice 0 e chega à propriedade nome. O resultado é a string Ana. Já /usuarios/1/nome falha, pois o documento só tem um elemento nesse array.
Você precisa distinguir uma falha de localização de um valor vazio ou nulo existente no JSON. O programa que usa o ponteiro deve tratar o erro conforme o contrato da integração.
Barras e til nos nomes das propriedades
A barra separa os segmentos, então uma propriedade chamada a/b precisa ser indicada por /a~1b. Dentro do segmento, ~1 representa a barra do nome e ~0 representa um til. Assim, /a~0b seleciona uma propriedade chamada a~b.
A string vazia identifica a raiz inteira. Uma barra isolada, /, seleciona uma propriedade de nome vazio no objeto da raiz. Essa diferença permite representar nomes que uma notação informal de caminhos poderia confundir.
Dúvidas frequentes
Perguntas frequentes sobre ponteiro JSON
- Qual é o ponteiro para o documento inteiro?
- A string vazia identifica o documento inteiro. Uma barra isolada identifica uma propriedade cujo nome é vazio, quando ela existe no objeto da raiz.
- O índice de um array pode ter zero à esquerda?
- O primeiro índice é 0. Os demais são escritos sem zeros à esquerda, como 1 e 12. Um segmento 01 não é um índice válido de array.
- Uma propriedade inexistente é criada pelo ponteiro?
- O ponteiro apenas identifica um valor. Quando uma etapa não encontra o valor correspondente, a avaliação falha. A aplicação que usa o ponteiro define como tratar esse erro.
Para continuar
Recursos relacionados
Documentação
RFC 6901: sintaxe e avaliação de JSON Pointer
Especifica os segmentos do ponteiro, os escapes ~0 e ~1, os índices de arrays e o tratamento de falhas na avaliação.
Abrir recursoSite de referência
DevSide: desenvolvimento colaborativo
O Desenvolvimento Colaborativo permite investigar com orientação técnica a leitura de campos JSON e os erros de integração no seu projeto.
Abrir recursoAplicação na formação
Vibe Coding: Do Zero ao MVP
Ao integrar aplicações, você precisa localizar o campo esperado no JSON e tratar caminhos que não existem na resposta.
Conhecer a formação
Fontes consultadas
Referências deste verbete
Este verbete ajudou você?
Obrigado pela resposta. Ela fica salva apenas neste navegador.