Null versus campos ausentes em APIs JSON

O que é

Numa resposta, "middleName": null, a ausência da chave middleName e "middleName": "" podem todos significar "sem nome do meio", mas também podem significar "desconhecido", "não solicitado" e "vazio". Numa requisição, as mesmas três formas podem significar "não alterar", "limpar o valor" e "definir como vazio". Os padrões assumem posições. O JSON Merge Patch (RFC 7396, citado) dá ao null num patch um significado especial: a remoção do membro no alvo. Por isso a RFC considera o formato inadequado para documentos que usam valores null explícitos. O ProtoJSON (citado) orienta os serializadores a não emitir null e os parsers a aceitar null como valor válido para qualquer campo, deixando o campo sem definição, como se estivesse ausente. O Google JSON Style Guide (citado) recomenda omitir propriedades cujo valor seja vazio ou null, a menos que haja uma razão semântica forte para mantê-las.

Por que importa

Clientes escritos em linguagens com tipos opcionais (ponteiros em Go, Option em Rust, undefined versus null em TypeScript) mapeiam esses casos de maneiras diferentes. Um endpoint de atualização que não distingue "omitido" de "null" ou limpa campos por acidente ou não consegue limpá-los de forma alguma.

Como aplicar

• Decida, para cada API, se as respostas emitem null nos campos opcionais não definidos ou se os omitem, documente a escolha e não misture as duas. A omissão mantém os payloads pequenos e segue o ProtoJSON; o null explícito mantém estável a lista de campos para consumidores tabulares.
• Em atualizações parciais, use a semântica de merge patch: ausente significa inalterado, null significa limpar, um valor significa definir. Como alternativa, aceite uma máscara de campos (updateMask=name,email) que liste os campos que a requisição pretende definir, o que também permite limpar sem usar null.
• Nunca use null para "não solicitado" em respostas com seleção de campos; omita o campo.
• Retorne coleções vazias como [], e não como null nem ausentes, para que os clientes possam iterar sem verificações.
• No schema, expresse a opcionalidade (required) separadamente da possibilidade de ser nulo (type: ["string", "null"]); um campo pode ser obrigatório e ainda assim aceitar null, ou ser opcional e nunca ser null.
• Informe o valor padrão que o servidor aplica quando um campo está ausente na criação.

Armadilhas

Desserializadores que transformam uma chave ausente num valor padrão (0, false, string vazia) antes de a aplicação vê-lo, de modo que a informação de "não definido" se perde. Corpos de PATCH gerados pela serialização de um objeto inteiro no cliente, que reenviam todos os campos e sobrescrevem alterações concorrentes. SDKs que não conseguem representar "explicitamente null" e, por isso, não conseguem limpar um campo.