Nulo, vacío y cero en el importe de un acta: tres cosas distintas

Un reporte de flota muestra “$ 0” en la columna de importe. Nadie escribió ese número: la respuesta traía una cadena sin caracteres, la exportación la volcó como celda sin contenido y la planilla la sumó como si fuera cero. Tres capas, tres decisiones defendibles, y una afirmación final que ninguna fuente hizo.

El valor nulo, el campo ausente y el cero ya están tratados en null, campo ausente o cero. Acá el foco es el vacío, el estado que casi ninguna capa intermedia conserva por su cuenta, y el recorrido donde los tres se mezclan.

Un vacío es un envase presente y sin contenido: una cadena sin caracteres, una lista sin elementos, un objeto sin propiedades. No es el nulo, el valor con el que el contrato declara que el dato no está disponible, ni una medición que dio cero. Confundirlos no rompe nada de inmediato: convierte un desconocimiento sobre una multa en una cifra.

El formato distingue más de lo que sobrevive al viaje

RFC 8259 enumera lo que puede ser un valor JSON: un objeto, un array, un número, una cadena o uno de los tres nombres literales false, null y true. Su gramática admite además la cadena de cero caracteres, el array sin elementos y el objeto sin miembros. Ninguna de esas tres formas es el valor nulo, y ninguna es el número cero.

{ "importe": 0 }
{ "importe": null }
{ "importe": "" }
{ "importes": [] }

Para el negocio deberían ser igual de distintas: cero es un importe que alguna jurisdicción informó; el nulo, el estado que el contrato haya documentado; la cadena vacía, un texto sin contenido; la lista vacía, una colección sin elementos. Esa última se lee junto con la cobertura: por sí sola no separa “no hay” de “no se pudo mirar”.

Los bordes donde las tres se mezclan

El JSON las separa; el recorrido posterior las junta. Conviene mirar cuatro pasos:

• la deserialización, donde el tipo del lenguaje y el generador de clientes deciden si el nulo y la cadena vacía caen en la misma variable;
• la persistencia, donde una columna de texto suele aceptar los dos y una numérica admite el nulo pero no la cadena vacía;
• la exportación tabular, donde el destino no tiene vocabulario para el matiz;
• el render final, donde la plantilla imprime lo que recibe y un espacio en blanco parece un dato prolijo.

La gramática de RFC 4180 admite un campo sin ningún carácter y el formato no define ningún valor nulo. Un nulo y una cadena vacía salen idénticos, y nadie puede reconstruir cuál era cuál salvo que las partes hayan acordado una convención por fuera del formato. Si ese archivo vuelve a entrar al sistema, el viaje de ida y vuelta ya perdió la distinción.

En el análisis pasa algo parecido: que una celda sin contenido quede afuera de un promedio o entre como cero en una suma es decisión de la herramienta, no del dato. Verificalo antes de publicar el total de deuda de una flota.

Lo que el esquema puede sostener

El vocabulario de validación de JSON Schema 2020-12 permite acotar el vacío: longitud mínima de una cadena, cantidad mínima de elementos de un array y de propiedades de un objeto. Si la cadena vacía no es admisible para el dominio, el esquema puede decirlo en vez de dejarlo a cada cliente.

OpenAPI 3.1 alinea su Schema Object con ese vocabulario, así que la regla vive en el contrato y no en un comentario de la documentación. Un campo puede exigirse presente y admitir nulo; otro puede admitir cadena y rechazar la cadena vacía.

El valor por defecto no cubre ese hueco: es una anotación de metadatos, y la especificación de OpenAPI aclara que documenta el comportamiento esperado del receptor en vez de insertar el valor en los datos. Declarar cero como predeterminado no impide que la jurisdicción mande una cadena vacía.

Y si el vacío tiene un sentido de negocio —un campo de observaciones que la jurisdicción publica en blanco—, documentalo como un estado con nombre en vez de dejarlo a criterio de cada consumidor.

Un ida y vuelta antes de creerle al reporte

Armá un caso por forma y hacelo recorrer el circuito completo: API, modelo interno, base, exportación e informe de multas. Como mínimo, número positivo; cero informado; nulo; cadena vacía; cadena de sólo espacios; lista vacía; objeto sin propiedades; y campo ausente, tratado aparte en campos opcionales.

La prueba pasa si al final cada forma sigue siendo distinguible de las otras, o si la que se perdió está declarada como tal. Falla en silencio cuando el reporte muestra un número donde la fuente no dijo nada.

Qué revisar antes de integrar

Pedile al contrato una representación canónica por estado, y una sola. Revisá qué hace tu deserializador con la cadena vacía y con el nulo, qué guarda la base y qué imprime la plantilla cuando no hay valor. En la exportación, documentá cómo se marca lo que no vino, sabiendo que el archivo no lo distingue solo.

Una multa en cero mal puesta no se ve como un error. Se ve como una respuesta.

Preguntas frecuentes

¿Una cadena vacía es lo mismo que un valor nulo?

No. Para el formato son dos cosas distintas: el nulo es un valor literal de JSON y la cadena vacía es un texto que existe con cero caracteres. Que tu lenguaje, tu ORM o tu base terminen guardando los dos en la misma representación es una decisión de esa capa, no algo que el contrato haya dicho.

¿Una lista vacía significa que no hay infracciones?

Sólo si la respuesta declara que la consulta terminó y con qué cobertura. Una colección sin elementos describe lo que se encontró, no lo que se llegó a mirar: con fuentes pendientes o caídas, el vacío no alcanza para concluir que no hay deuda.

¿Se puede recuperar la diferencia después de exportar a CSV?

No con el archivo solo. La gramática de RFC 4180 admite un campo sin ningún carácter y el formato no define ningún valor nulo, así que un nulo y una cadena vacía salen idénticos. Si la distinción importa, hay que transportarla en una columna aparte o acordar una convención explícita entre las dos partes.

¿Alcanza con declarar un valor por defecto en el esquema?

No. En JSON Schema 2020-12 el valor por defecto está definido entre las anotaciones de metadatos: sugiere qué poner, pero no lo inserta en la respuesta ni lo vuelve exigible al validar. Para impedir una cadena vacía o una lista sin elementos hacen falta las restricciones de longitud y de cantidad, y una decisión explícita sobre qué hacer si llegan igual.

Notas relacionadas