Convertir NDJSON a TOML

Casi nadie convierte a TOML para que lo lea una máquina: el NDJSON de origen ya servía perfectamente para eso, y cualquier lenguaje lo procesa sin instalar nada. Lo que se busca aquí es otra cosa. El archivo va a quedarse dentro de un repositorio, alguien va a abrirlo dentro de seis meses para cambiar un valor, y otra persona va a mirar ese cambio en una revisión antes de aprobarlo.

Piensa en el tipo de tabla que acaba en esa situación: los tipos de IVA aplicables por categoría, los días festivos de cada comunidad o provincia, los prefijos postales de una zona de reparto, la lista de entidades con las que un servicio tiene convenio. Son datos que cambian pocas veces, que cambian por un motivo concreto y documentable, y que una persona edita a mano. Ese es exactamente el terreno donde TOML compensa, y es el único.

Existe la idea de que TOML no puede representar lo que representa JSON, y en el caso de una lista de registros es sencillamente falsa. El mecanismo se llama arreglo de tablas y se escribe repitiendo el mismo encabezado entre corchetes dobles: tres apariciones de [[items]] son tres registros, cada uno con sus claves debajo. Es la misma construcción con la que Cargo declara dependencias.

Frente al JSON del que viene ocupa más líneas y se edita mucho mejor. Añadir un registro es copiar cuatro renglones en lugar de contar llaves y acordarse de la coma que separa los elementos. Y en una diferencia de dos versiones del archivo, un cambio en un registro afecta solo a su bloque, en vez de mover la puntuación de los vecinos. Para algo que va a mantener una persona, ahí se agota el argumento y no hace falta más.

Un documento TOML tiene que ser una tabla en su nivel superior, y un archivo delimitado por saltos de línea es una lista sin nombre propio. Alguien tiene que ponerle uno, y quien convierte no puede saber cuál: en el origen no hay nada que diga si esas líneas son proveedores, tarifas o municipios. Así que la lista recibe un nombre de relleno y la salida es una sucesión de bloques [[items]], uno por línea.

Cambiarlo es la primera edición que hay que hacer y es una sustitución sobre los encabezados: a [[tarifas]], a [[festivos]], a [[dependencies]], a lo que espere la herramienta que va a leer el archivo. Que el nombre sea obviamente provisional está pensado: un conversor que se inventara un nombre plausible produciría archivos que parecen correctos y no lo son, y esa es la clase de error que se descubre tarde.

Esta es la ventaja silenciosa de TOML frente a cualquier destino tabular para el mismo archivo. Un CSV, un Parquet o una tanda de sentencias INSERT tienen que reconciliar todos los registros en un único juego de columnas y rellenar huecos donde un registro no traía nada. Un arreglo de tablas no: cada bloque lleva exactamente las claves que tenía su línea, ni una más.

De modo que un archivo en el que los registros más recientes ganaron un campo se convierte sin nulos, sin celdas vacías y sin ensanchar nada. El resultado se lee como lo que es —una lista de cosas que se parecen bastante entre sí— y no como una cuadrícula llena de huecos. Para un conjunto que se fue formando por acumulación, esa suele ser también la representación más honesta de su historia.

TOML no tiene literal nulo y el escritor no se inventa uno. Una clave cuyo valor en JSON era null simplemente no se escribe dentro del bloque, ni en el primer nivel del registro ni a ninguna profundidad por debajo. La clave no queda vacía: queda ausente.

Que eso importe o no es una pregunta sobre el programa que va a leer el archivo. Muchos tratan igual una clave ausente y un valor vacío, porque en los dos casos recurren a un valor por defecto, y ahí no se ha perdido nada. Donde la diferencia decide un comportamiento, la conversión ha cambiado los datos en silencio, y la defensa barata es buscar null en el origen antes de convertir en lugar de comparar los dos archivos después: una línea que falta se ve muchísimo peor que una línea que cambió.

Un registro con un objeto dentro produce una subtabla debajo de su bloque: un objeto de contacto dentro de cada entrada aparece como un encabezado [items.contacto] con sus claves a continuación. La profundidad se expresa en el nombre del encabezado y no con márgenes crecientes, así que tres niveles siguen quedando pegados al margen izquierdo.

Conviene saber que aquí el árbol se conserva, cosa que no ocurre en todos los destinos: hacia CSV, TSV, SQL, INI, XLSX o Parquet lo anidado se aplana en una columna por hoja con la ruta como nombre, mientras que JSON, YAML, XML, NDJSON y TOML mantienen la estructura. Es legal a cualquier profundidad y desagradable a partir de la segunda: un encabezado como [items.metadatos.origen.sistema] es válido y no lo disfruta nadie. Cuando aparece, la señal es sobre los datos y no sobre la conversión.

TOML 1.0 tiene cuatro tipos de fecha y hora, incluida una fecha con desfase horario que es un valor de verdad y no una cadena. JSON no tiene ninguno: toda marca temporal en todo archivo JSON es texto o un número por convención. Así que un valor como "2024-01-01T00:00:00Z" se escribe como cadena entrecomillada, que es lo único que el origen permitía afirmar.

Es correcto y no es todo lo que el formato de destino sabría expresar. Si la herramienta que lee el archivo quiere una fecha real, quitar las comillas de esas líneas es la corrección completa y no hay que tocar nada más. Es una tarea razonable para el mismo rato en el que estás renombrando los encabezados, porque después nadie vuelve a abrir el archivo con esa intención.

JSON no admite comentarios, y un archivo hecho de líneas JSON tampoco. De ahí que los motivos detrás de los valores de una tabla de datos vivan hoy en un mensaje de confirmación de hace dos años, en un hilo de correo o en la cabeza de alguien que ya no está en el proyecto. El archivo transporta los valores y ninguna de las razones.

En cuanto el archivo es TOML, esas razones caben al lado de las entradas: qué disposición del boletín oficial fijó este tipo impositivo, por qué esta fila está excluida de las pruebas, con qué identificador externo tiene que coincidir un valor, qué se rompe si se reordena la lista. Es información que un archivo generado nunca podría llevar consigo, y los primeros minutos después de convertir son el momento más barato para escribirla.

Unas pocas docenas se llevan bien. Unos cientos producen un archivo que nadie leerá entero pero que cualquier programa sigue procesando en un instante. Unos miles de bloques son un archivo de configuración solo de nombre, y a esa altura todas las propiedades que hacían atractivo a TOML —diferencias legibles, edición manual, un comentario junto al valor— han dejado de aplicarse.

La regla de parada merece aplicarse en serio: si nadie va a abrir el archivo, no lo conviertas a un formato de configuración. CSV pesa menos y lo lee todo, JSON es lo que los datos ya eran, y una base de datos es lo que quieres si la lista se va a consultar. TOML se gana el sitio únicamente cuando una persona va a mantener el resultado con sus propias manos.

Este es el error que comete casi todo el mundo con TOML y conviene conocerlo antes de empezar a editar el archivo, porque el conversor no puede protegerte de él. Un encabezado de tabla reclama todas las líneas que se escriban por debajo hasta que aparezca el siguiente encabezado. No hay forma de cerrarlo.

De ahí que añadir una clave de versión o de fecha de actualización al final del archivo la meta dentro del último bloque [[items]] en lugar de dejarla en el nivel superior, y que el archivo siga siendo válido mientras significa otra cosa. Las claves generales van arriba del todo, por encima del primer encabezado de corchetes dobles. Si el archivo va a durar, ese es el sitio donde ponerlas desde el primer día.

Las dos mitades son JavaScript ejecutándose en esta página: el archivo se lee línea a línea y el TOML lo escribe una biblioteca pequeña que se carga solo cuando hace falta. No se sube nada, no hay cuenta, no hay cola y el techo del plan gratuito son 100 MB por archivo, una cifra que un archivo apropiado para esta conversión no roza ni de lejos.

El argumento de privacidad sigue valiendo a esta escala, aunque parezca menor. Un juego de datos de prueba es muy a menudo material real con los nombres puestos, y una semilla para una base de datos de desarrollo suele ser un recorte de producción. No enviarlo a ninguna parte cuesta menos aquí que en un volcado de registros, y sigue siendo el comportamiento correcto por defecto.