Campos nulos frente a campos ausentes en las API JSON

Qué es

En una respuesta, "middleName": null, la ausencia de la clave middleName y "middleName": "" pueden significar todas ellas «sin segundo nombre», pero también pueden significar «desconocido», «no solicitado» y «vacío». En una petición, esas mismas tres formas pueden significar «no cambiar», «vaciar el valor» y «fijar como vacío». Los estándares toman postura al respecto. JSON Merge Patch (RFC 7396, citada) da a null, dentro de un patch, un significado especial: la eliminación del miembro del destino, razón por la cual la RFC califica el formato de inadecuado para documentos que usan valores null explícitos. ProtoJSON (citado) indica a los serializadores que no emitan null, y a los analizadores que acepten null como valor legal para cualquier campo, dejando ese campo sin establecer, como si estuviera ausente. La guía de estilo JSON de Google (citada) aconseja omitir las propiedades cuyo valor sea vacío o null, salvo que exista una razón semántica de peso para que estén presentes.

Por qué importa

Los clientes escritos en lenguajes con tipos opcionales (los punteros de Go, Option de Rust, undefined frente a null en TypeScript) representan estos casos de forma distinta. Un endpoint de actualización que no puede distinguir «omitido» de «null» acaba vaciando campos por accidente, o directamente no puede vaciarlos.

Cómo aplicarlo

• Decidir, por API, si las respuestas emiten null para los campos opcionales sin establecer o los omiten, documentarlo, y no mezclar ambos enfoques. La omisión mantiene las cargas útiles pequeñas y coincide con ProtoJSON; el null explícito mantiene estable la lista de campos para consumidores tabulares.
• Para las actualizaciones parciales, usar la semántica de merge-patch: ausente significa sin cambios, null significa vaciar, un valor significa establecer. Como alternativa, aceptar una máscara de campos (updateMask=name,email) que liste los campos que la petición pretende establecer, lo cual también permite vaciar sin usar null.
• No usar nunca null para «no solicitado» en respuestas con selección de campos; omitir el campo.
• Devolver las colecciones vacías como [], no como null ni omitidas, de modo que los clientes puedan iterar sin comprobaciones.
• En el esquema, expresar la opcionalidad (required) por separado de la nulabilidad (type: ["string", "null"]); un campo puede ser obligatorio y a la vez nulable, u opcional y nunca null.
• Indicar el valor por defecto que aplica el servidor cuando un campo está ausente en la creación.

Trampas

Deserializadores que convierten una clave ausente en un valor por defecto (0, false, cadena vacía) antes de que la aplicación lo vea, con lo que se pierde el «sin establecer». Cuerpos de PATCH producidos al serializar todo un objeto del lado del cliente, que reenvían todos los campos y sobrescriben cambios concurrentes. SDK que no pueden representar «null explícito» y que, por tanto, no pueden vaciar un campo.