Resumo

  • JSON Type Definition verifica se uma instância satisfaz um contrato estrutural limitado de propósito; a aceitação não atesta a afirmação contida nela.
  • Oito formas exclusivas, abertura local de campos desconhecidos e dois ponteiros de erro reduzem interpretações divergentes.
  • Depois do esquema vêm identidade, autorização, regras do domínio, prevenção de replay, persistência e comprovação do resultado.

Uma API recebe um evento de aprovação com todos os campos corretos. O tipo pertence à enumeração, o identificador é string, o horário tem formato válido. O corpo também pode ter sido copiado de uma chamada anterior, assinado por outra conta ou produzido antes da revogação de uma permissão. O esquema enxerga a forma comum aos casos; não enxerga a história que os separa.

O JSON Type Definition do RFC 8927 foi desenhado exatamente para essa tarefa menor. Ele descreve estruturas JSON frequentes, facilita gerar tipos em linguagens convencionais e oferece locais de erro previsíveis. Sua expressividade é intencionalmente inferior à de linguagens mais amplas. A renúncia diminui o espaço em que implementações independentes podem discordar.

O experimento depende de uso real

O RFC veio do Independent Stream, tem status Experimental e não representa consenso da IETF nem Internet Standard. O próprio texto mede o sucesso pela existência de várias implementações independentes que usem JTD para intercambiar informação. Publicação não é evidência de implantação.

Há oito formas mutuamente exclusivas: vazia, referência, tipo, enumeração, elementos, propriedades, valores e discriminador. A forma vazia aceita tudo. ref aponta para definições da raiz. properties modela um registro; values, um mapa; discriminator, uma união marcada por string.

As definições só podem aparecer na raiz, e uma forma não pode competir com outra. Ramos do discriminador não redefinem a etiqueta. Esses limites tornam o significado menos dependente de ordem, profundidade ou preferência da biblioteca.

CDDL consegue dizer mais e é usado pelo próprio RFC para descrever a sintaxe de JTD. O contraste é honesto: o mínimo compartilhado não pretende substituir toda política local.

Uma aprovação sem restrição

A forma vazia nunca rejeita uma instância nem gera erro. Portanto, o recibo “passou em JTD” é incompleto sem hash e versão do esquema, implementação e modo. Uma luz verde pode corresponder a um contrato rico ou à ausência total de restrição.

metadata pode orientar documentação, geração de código ou uma ferramenta local. Outras partes não precisam entendê-la. Se metadata altera a validação, somente um acordo fora de banda torna esse comportamento comum. Uma anotação não conquista autoridade por parecer normativa.

Na linguagem das camadas de realidade de Heng Lu, o resultado descreve a relação entre mensagem e contrato executado. Não cria os fatos mencionados pela mensagem.

A permissão para desconhecidos é local

properties separa campos obrigatórios dos opcionais e rejeita nomes não declarados por padrão. additionalProperties:true pode admiti-los, mas a escolha vale apenas naquele objeto. Objetos internos não herdam a abertura.

Isso permite que o envelope aceite futura telemetria enquanto uma instrução de pagamento aninhada permaneça fechada. Bibliotecas que expõem uma única chave global apagam uma distinção de risco. O registro precisa dizer onde o campo apareceu e qual regra local decidiu.

Compatibilidade não é sinônimo de aceitar tudo. Um consumidor antigo pode ignorar justamente a nova instrução que mudava o sentido do evento. Quem assume o risco preserva a decisão futura sobre cada fronteira.

Coordenadas de erro não são autoridade

O erro padronizado combina instancePath, apontando para o valor recusado, e schemaPath, apontando para a regra. Ambos seguem JSON Pointer. Essa dupla permite reproduzir a falha sem transformar uma mensagem genérica em adivinhação.

A ordem dos erros, porém, não é especificada. O primeiro item não carrega prioridade, causalidade ou gravidade. E um ponteiro só localiza; não decide quem pode corrigir. Automatizar a alteração do campo apontado exige uma política adicional, explícita e reversível.

Um timestamp correto ainda pode mentir

JTD reconhece booleanos, strings, floats, inteiros de 8 a 32 bits com ou sem sinal e timestamps. O timestamp deve seguir RFC 3339 conforme refinado pelas regras do Atom. A gramática uniformiza a representação, não autentica o relógio nem confirma o evento.

O RFC omite int64 e uint64 porque o ecossistema JSON não preserva universalmente toda essa precisão. I-JSON recomenda uma faixa menor interoperável. Em vez de oferecer um nome de tipo que sugerisse uma garantia falsa, JTD se abstém.

O discriminador também só seleciona uma variante. Uma etiqueta account_deleted pode obrigar a presença do ID, mas não prova a exclusão. Identidade do emissor, autorização, aceitação, escrita durável e leitura posterior continuam separados.

Esquemas também consomem recursos

Referências circulares podem prender um avaliador ingênuo. RFC 8927 recomenda detectá-las e abortar quando o esquema vem do usuário, evitando negação de serviço. RFC 8259 permite impor limites a tamanho, profundidade e precisão.

Operação segura define orçamentos de bytes, níveis, expansões, erros e tempo. Também classifica a origem do esquema: artefato confiável, entrada do locatário ou dependência externa. Ser JSON válido não torna a carga inofensiva.

Fontes

  1. RFC 8927 — JSON Type Definition
  2. RFC 8259 — Formato de intercâmbio JSON
  3. RFC 7493 — Formato de mensagem I-JSON
  4. RFC 6901 — JSON Pointer
  5. RFC 3339 — Data e hora na Internet
  6. RFC 4287 — Formato de distribuição Atom
  7. RFC 8610 — Concise Data Definition Language
  8. Heng Lu — Running-Code Primacy
  9. Heng Lu — Minimum Initial Specification, Localized Future Decision, and Voluntary Adoption
  10. Heng Lu — On Reality Layers, Symbolic Power, and Why Clarity Feels So Hostile