Null, vacío, cero o campo ausente: cómo evitar cambios de significado en JSON para una API

Cuatro representaciones distintas

En un objeto JSON, null, "", 0 y una propiedad omitida son representaciones distintas. null es un valor especial de JSON; la documentación de IBM señala que puede utilizarse con campos de distintos tipos, incluidos matrices, objetos y tipos numéricos ([IBM: Manejo de matrices y objetos nulos y vacíos JSON](https://www.ibm.com/docs/es/baw/25.0.x?topic=format-handling-json-null-empty-arrays-objects)). "" es una cadena vacía y 0 es un número. Una propiedad ausente significa que la clave no aparece en el objeto. Por eso, describir cualquiera de esos casos como simplemente «vacío» puede ocultar una diferencia importante al revisar o transformar datos.

Por ejemplo, estos objetos no contienen la misma representación: {"nota": null}, {"nota": ""}, {"nota": 0} y {}. En el último objeto no se envía la clave nota; en los tres primeros sí aparece, aunque con valores distintos. El ejemplo permite comparar la forma del payload, pero no establece qué hará una API con cada variante.

Las diferencias del payload no determinan por sí solas el resultado de una operación. No existe aquí una regla universal para interpretar una propiedad omitida, null, una cadena vacía o cero, en particular al actualizar un recurso. El contrato del endpoint concreto debe aclarar qué se espera y cómo se interpretan esos casos. No conviene deducir la intención del usuario ni la operación que realizará el servicio a partir del valor aislado.

Separar primero las representaciones ayuda a formular preguntas precisas: ¿el dato no se proporcionó?, ¿se proporcionó una respuesta en blanco?, ¿se indicó explícitamente cero? Esas preguntas describen posibles intenciones, no una semántica automática de JSON. La correspondencia entre intención, representación y resultado debe confirmarse para el campo y la operación en cuestión.

• null: valor JSON explícito.
• "": cadena vacía explícita.
• 0: número explícito.
• Propiedad ausente: la clave no está incluida en el objeto.

Confirma el significado en el contrato de la API

Para cada propiedad, revisa la documentación del endpoint y anota qué tipo acepta, si es obligatoria y si admite null. Si se trata de una actualización, busca también qué indica el contrato sobre una propiedad omitida, una propiedad enviada como null y una cadena vacía. No traslades automáticamente la regla de otra operación ni la de otro campo: aunque dos propiedades tengan nombres o usos parecidos, la documentación que debes consultar es la de la operación concreta.

Conviene distinguir entre preguntas que el contrato responde y asuntos que siguen pendientes. Si la documentación solo dice que un campo es una cadena, eso no aclara necesariamente qué significa omitirlo o enviar una cadena vacía. Si solo muestra un ejemplo con un valor numérico, no confirma por sí solo qué ocurre con cero. Registra esas dudas en vez de completar los vacíos con una suposición; solicita confirmación o plantea una prueba controlada cuando sea posible.

Comprueba también que el tipo del dato de origen sea el previsto. Por ejemplo, "0042" es una cadena tal como está escrita, mientras que 42 es un número; no los conviertas en equivalentes sin una regla confirmada. Si se elimina el cero inicial, cambia la representación que se envía. La decisión de conservarlo, transformarlo o tratarlo de otra forma debe proceder del requisito acordado y del contrato, no de una conversión automática no revisada.

En .NET, Microsoft Learn explica cómo configurar System.Text.Json para respetar las anotaciones de nulabilidad durante la serialización y la deserialización ([Microsoft Learn: Respetar las anotaciones que aceptan valores NULL](https://learn.microsoft.com/es-es/dotnet/standard/serialization/system-text-json/nullable-annotations)). Esta referencia trata la configuración de .NET; no establece por sí sola cómo interpretará el valor la API de destino. Mantener separados esos dos niveles evita confundir la forma en que se maneja un dato en el código con el significado que el servicio documenta para el payload.

• Registra por propiedad el tipo esperado, si es obligatoria y las reglas documentadas para null y la omisión.
• Marca como pendiente cualquier comportamiento que el contrato no defina; no lo sustituyas por una suposición.

Documenta el mapeo antes de transformar los datos

Como práctica general de integración, crea una tabla que conecte el estado recibido con la intención de negocio y la salida JSON prevista. Para un campo de comentario, por ejemplo, registra por separado una respuesta no proporcionada y una respuesta en blanco. Para una cantidad, distingue una entrada vacía del número 0. La tabla no debe imponer una conversión universal: sigue las reglas confirmadas para esa API y deja claro qué aspecto todavía no está definido.

Una fila puede describir el dato tal como llega, sin decidir automáticamente qué se enviará. Por ejemplo: campo de origen «comentario»; estado recibido «sin respuesta»; intención «pendiente de confirmar»; regla documentada «no especificada»; salida «no definida». Otra fila puede registrar una cadena vacía y una tercera una respuesta escrita. Así, una persona que revise el mapeo puede identificar qué decisiones faltan antes de que el flujo transforme los valores.

Haz explícita la diferencia entre conservar un dato existente, limpiarlo y asignarle cero cuando esas intenciones sean relevantes para el flujo. Estos términos pueden describir objetivos distintos, pero no dictan qué representación JSON corresponde a cada uno. Si el contrato define la salida adecuada, anótala; si no lo hace, señala la limitación y acuerda una alternativa antes de automatizar.

Mantén el mapeo ligado al campo y al endpoint para el que se documentó. Una regla anotada para una propiedad no debe reutilizarse sin confirmación en otra. También resulta útil conservar ejemplos de entrada y salida junto a la regla, porque hacen visible si una transformación cambia el tipo, omite una clave o envía un valor explícito.

• Plantilla práctica: campo de origen | estado recibido | intención | regla documentada | propiedad y valor enviados.
• Incluye ejemplos concretos del origen para que otras personas puedan revisar el mapeo.
• Separa las decisiones confirmadas de las preguntas pendientes.

Prueba casos representativos

Como recomendación de trabajo, prepara ejemplos pequeños que cubran los estados pertinentes para cada campo. Para un comentario, podrías comparar un objeto con "comentario": null, otro con "comentario": "" y otro sin la clave. Para una cantidad, prueba null, 0 o la omisión solo si el contrato permite esos casos. Añade también un valor habitual para comprobar el recorrido normal. Estos ejemplos sirven para revisar qué payload se construye; no sustituyen la explicación del contrato ni permiten asumir un efecto no documentado.

Anota para cada ejemplo cuál es la salida esperada y por qué se considera correcta según la regla acordada. Si no puedes escribir esa justificación porque el contrato no aclara el caso, clasifícalo como pendiente en lugar de inventar una expectativa. Esta separación hace más fácil revisar el ejercicio: una discrepancia puede deberse a una transformación del dato o a que todavía falta decidir qué debe significar el caso.

Revisa también los valores que una transformación podría modificar, como una cadena con espacios o un identificador con ceros iniciales. Decide de forma explícita si se conservan o se transforman según el requisito acordado. Mantén diferenciadas cadenas como "0042" y números como 42, salvo que una regla confirmada indique lo contrario. El ejemplo no establece que un formato sea siempre correcto; invita a comprobar que el formato generado coincide con lo esperado.

Compara el payload generado con el esperado y revisa la respuesta de la API. Que el JSON esté bien formado no demuestra por sí solo que coincida con el contrato ni que produzca el efecto deseado. Si el resultado observado no coincide con lo acordado, identifica qué representación se envió y qué regla se utilizó antes de cambiar la transformación.

• Incluye los casos normal, vacío, null, cero y propiedad omitida cuando correspondan al campo y estén permitidos.
• Mantén diferenciadas las cadenas, como "0042", y los números, como 42, salvo que una regla confirmada indique lo contrario.
• Para cada caso, anota la salida esperada o deja claro que la interpretación sigue pendiente.

Valida los cambios y conserva un historial útil

Como lista de comprobación general, revisa la sintaxis JSON, los nombres y tipos de las propiedades y las reglas documentadas del endpoint. Son aspectos distintos: un payload puede ser JSON válido y no coincidir con el contrato. Antes de ampliar un envío automatizado, compara las salidas de los casos preparados con las esperadas y revisa las respuestas recibidas. El objetivo de estas comprobaciones es detectar diferencias entre lo acordado y lo que realmente se construye o se recibe, sin atribuir a una respuesta un significado que el contrato no define.

Cuando cambie el mapeo o la definición del endpoint, vuelve a revisar los ejemplos pertinentes y registra qué regla se modificó. Conserva una descripción breve del caso, el valor enviado, la salida esperada y el resultado observado, con el nivel de detalle necesario para entender la revisión. No conviertas ese registro en una fuente alternativa de semántica: si una observación contradice lo documentado o no se entiende, consulta el contrato y aclara la regla.

Al investigar una discrepancia, sigue el dato desde su estado de origen hasta la representación JSON final. Comprueba si la clave se incluyó, qué valor se envió y qué tipo tiene, y compara ese resultado con el mapeo acordado. Esta revisión ayuda a localizar en qué punto se apartan los ejemplos, sin asumir que null, una cadena vacía, cero y la omisión son intercambiables.

Estas son recomendaciones generales de trabajo; no definen el comportamiento de una API particular. La decisión final sobre una propiedad debe apoyarse en el contrato del endpoint. Si el contrato no resuelve un caso necesario, deja la automatización de ese caso pendiente hasta obtener una interpretación confirmada.

• Lista de revisión: contrato consultado, mapeo documentado, casos pertinentes comprobados y respuestas revisadas.
• Si el resultado observado no coincide con el esperado, pausa la automatización hasta aclarar y corregir la regla.

Preguntas frecuentes