Guia de Padrões JSON: RFC 6901, 6902 e 7396

O JSON tornou-se o padrão de fato para troca de dados na web. No entanto, à medida que as APIs se tornam mais complexas, objetos JSON simples muitas vezes não são suficientes. Os desenvolvedores precisam de formas padronizadas de referenciar partes específicas de um documento JSON e de descrever as alterações nesses documentos. É aqui que entram o RFC 6901 (JSON Pointer), o RFC 6902 (JSON Patch) e o RFC 7396 (JSON Merge Patch).

O que são JSON Pointer e Patch?

• RFC 6901 (JSON Pointer): Define uma sintaxe de string para identificar um valor específico dentro de um documento JSON. É como um "endereço" para um dado.
• RFC 6902 (JSON Patch): Define uma estrutura de documento JSON para expressar uma sequência de operações a serem aplicadas a um documento JSON. É como um "diff" ou um "log de transações".
• RFC 7396 (JSON Merge Patch): Fornece uma maneira mais simples de descrever alterações enviando um documento de "patch" que se parece com o documento de destino, mas contém apenas os campos alterados.

1. RFC 6901: JSON Pointer

O JSON Pointer usa uma sintaxe separada por barras (/) para navegar pela hierarquia de um objeto JSON.

Regras de Sintaxe:

• / representa a raiz.
• /foo aponta para o valor da chave "foo".
• /foo/0 aponta para o primeiro elemento do array "foo".
• ~1 é usado para representar uma / literal.
• ~0 é usado para representar uma ~ literal.

Exemplo:

{
  "biscuits": [
    { "name": "Digestive" },
    { "name": "Choco" }
  ]
}

O ponteiro /biscuits/1/name seria resolvido como "Choco".

2. RFC 6902: JSON Patch

O JSON Patch é um array de objetos de operação. Cada objeto deve ter um campo op.

Operações:

• add: Adiciona um valor no caminho especificado.
• remove: Remove o valor no caminho.
• replace: Substitui o valor no caminho.
• move: Move um valor de um caminho para outro.
• copy: Copia um valor de um caminho para outro.
• test: Testa se um valor em um caminho é o esperado.

Exemplo de Patch:

[
  { "op": "replace", "path": "/biscuits/0/name", "value": "Oatmeal" },
  { "op": "add", "path": "/biscuits/-", "value": { "name": "Ginger" } }
]

O - em /biscuits/- significa "o final do array".

3. RFC 7396: JSON Merge Patch

O JSON Merge Patch é muito mais simples que o RFC 6902. Você simplesmente envia um objeto JSON que representa o estado final desejado dos campos que deseja alterar.

Regras:

• Se o patch contiver um campo com um valor não nulo, esse campo será atualizado ou adicionado.
• Se o patch contiver um campo com um valor null, esse campo será removido do destino.
• Não é adequado para aplicar patches em arrays (ele substitui o array inteiro).

Exemplo:

Destino:

{ "a": "b", "c": "d" }

Patch:

{ "a": "z", "c": null, "e": "f" }

Resultado:

{ "a": "z", "e": "f" }

Comparação: Patch vs. Merge Patch

Recurso	RFC 6902 (Patch)	RFC 7396 (Merge Patch)
Complexidade	Alta (Array de operações)	Baixa (Baseado em objetos)
Eficiência	Muito Alta (Cirúrgico)	Moderada (Nível de campo)
Suporte a Arrays	Suporte total	Ruim (substitui o array inteiro)
Operações Atômicas	Sim (operação test)	Não
Ideal para	Mudanças de estado complexas	Atualizações simples de propriedades

Perguntas Frequentes FAQ

P: Qual devo usar para minha API? R: Use o JSON Merge Patch (7396) para atualizações simples de recursos onde você não se importa com a manipulação precisa de arrays. Use o JSON Patch (6902) para recursos complexos, requisitos de alto desempenho ou quando precisar de operações atômicas de "teste e definição".

P: Posso usar o JSON Pointer na minha URL? R: Sim, é comum usar JSON Pointers em fragmentos de URI (por exemplo, example.com/schema.json#/definitions/user).

P: Como lidar com caracteres especiais em chaves? R: Use ~1 para / e ~0 para ~. Por exemplo, uma chave chamada a/b é referenciada como /a~1b.

Ferramentas Relacionadas

• Formatador e Validador JSON - Use para validar seus documentos Patch ou Merge Patch.
• Conversor de JSON para CSV - Transforme seus dados JSON em tabelas para análise.