Um nome de membro ainda não é um caminho
Considere um objeto JSON cuja chave é draft/a~b e cujo valor é outro objeto contendo estado. A barra pertence à chave; não cria um nível aninhado. Um ponteiro JSON, por outro lado, identifica um valor através de tokens de referência separados por barras. O ponteiro /orders/0/item poderia endereçar um item dentro de uma matriz, onde 0 é um índice de matriz. Copiar um nome de membro bruto em um ponteiro sem escapar pode, portanto, endereçar o lugar errado ou falhar completamente.
O RFC 6901 define dois escapes dentro de cada token: um til torna-se ~0 e uma barra torna-se ~1. O ponteiro inteiro também começa com uma barra para cada segmento, enquanto o ponteiro vazio se refere ao documento inteiro. Esta notação diz respeito a caracteres em um caminho, não ao conteúdo do valor sendo endereçado. Ele não altera o JSON objeto em si. Use a ferramenta token quando estiver montando um caminho a partir de um nome de membro fornecido por dados ou um usuário.
Construa o exemplo um segmento de cada vez
Para a chave draft/a~b, primeiro substitua o tilde por ~0, depois a barra por ~1. O token escapado é draft~1a~0b. Prefixe uma barra e adicione o estado de membro separado para obter /draft~1a~0b/state. O conversor incorporado abaixo executa a etapa de token; ele intencionalmente não adiciona a barra inicial porque você pode querer colocar o token em qualquer lugar em um ponteiro mais longo. Compare sua saída com os três estágios no diagrama.
A ferramenta de token inverso substitui ~1 com barra antes de substituir ~0 com tilde. Essa ordem importa: decodificar ~01 como ~1, então decodificá-lo novamente como barra mudaria o nome original. Um token de ponteiro não é codificação de porcentagem de URL. Se um aplicativo coloca um ponteiro dentro de um fragmento de URL, essa camada externa de URI tem regras de codificação adicionais. Mantenha a sintaxe do ponteiro e a sintaxe da URL separadas ao depurar um link ou solicitação de API.
- Chave bruta: draft/a~b
- Token escapado: draft~1a~0b
- Caminho completo: /draft~1a~0b/state
O que o achatamento realmente produz
A ferramenta flatten caminha um objeto JSON e escreve valores de folha sob chaves que se parecem com ponteiros JSON completos. Para um objeto contendo um membro de estado abaixo de draft/a~b, uma entrada plana é /draft~1a~0b/state com o mesmo valor de folha. Isso pode tornar os dados aninhados mais fáceis de comparar, listar ou exportar. A ferramenta reversa lê essas chaves de caminho para reconstruir um objeto aninhado, desde que os caminhos não colidam ou contradigam um ao outro. Uma entrada plana ainda é um membro de objeto JSON, não uma operação de pesquisa automática.
Esta ferramenta em particular trata matrizes como valores de folha; não faz entradas separadas /0 e /1 para seus elementos. Objetos vazios são folhas também. Um ponteiro JSON geral pode endereçar um índice de matriz, mas uma listagem plana desta ferramenta não enumera esses índices. Se um caminho atribuir um escalar em /a enquanto outro tenta atribuir /a/b, a operação reversa deve rejeitar o conflito. Preserve o JSON original ao mudar as chaves de caminho manualmente.
Um fluxo de trabalho seguro para dados baseados em caminhos
Comece com JSON válido e decida se você precisa de um endereço único ou de uma visualização plana completa. Para um endereço, divida a rota pretendida em nomes de membros reais, escape cada nome separadamente e junte os tokens com barras iniciais. Não escape o ponteiro inteiro em uma passagem: isso transformaria as barras separadoras em parte de um nome. Se você precisar inspecionar muitos valores de folha, nivele o objeto e revise as chaves geradas antes de compartilhá-las com outro sistema.
Ao restaurar dados, verifique se cada chave de caminho plana começa com uma barra e se seus ~ escapes são válidos. Fique atento a atribuições duplicadas ou conflitantes, arrays tratados como folhas e chaves literais que contêm pontos ou barras. Teste uma viagem de ida e volta com um objeto pequeno contendo ambos os caracteres de pontuação e, em seguida, compare as estruturas JSON analisadas em vez de recuo. Os padrões descrevem a sintaxe do ponteiro; a política exata de nivelamento é um recurso desta ferramenta local e deve ser verificada antes de construir um fluxo de trabalho em torno dela.