Convertir TOML a JSON

TOML lleva años siendo el estándar del empaquetado de Python y de Rust, y lo que rodea a un repositorio con frecuencia no ha ido al mismo ritmo. Un paso de integración continua que tiene `jq` y poco más, un script de Node que necesita sacar la versión de un `Cargo.toml`, un panel que cuenta dependencias en doscientos repositorios: los tres saben leer JSON y ninguno sabe leer TOML sin añadir una dependencia.

Ese es el caso que atiende esta conversión, y funciona limpiamente porque los dos modelos de datos se solapan casi por completo. Un TOML es una tabla de pares clave-valor con anidamiento y listas, que es un objeto JSON con anidamiento y listas. Lo interesante son los cuatro sitios donde TOML sabe algo que JSON no sabe.

Una cabecera entre corchetes se convierte en un objeto anidado, y una cabecera con puntos anida varios niveles de golpe: una cabecera escrita para una herramienta y otra para un analizador debajo producen un objeto dentro de otro objeto, de modo que la ruta del JSON coincide exactamente con la cabecera. No hay nada que interpretar sobre la estructura.

La cabecera entre corchetes dobles es la lista de tablas y se convierte en una lista JSON de objetos, con una entrada por aparición. Es lo que sostiene los autores de un paquete de Python, los binarios de un crate de Rust y los objetivos de una compilación, y es la construcción que más preocupa a la gente y menos debería. El orden se conserva.

TOML es el único formato de esta familia con tipos temporales de verdad: fecha y hora con desfase, fecha y hora local, fecha local y hora local están en la especificación, y el analizador las devuelve como objetos de fecha. JSON no tiene tipo de fecha, así que cada una acaba siendo una cadena.

Lo que aquí está resuelto con cuidado es que la cadena no aplana los cuatro tipos en uno. El analizador devuelve un objeto que recuerda cuál de los cuatro era, y el escritor lo respeta: una fecha sin hora sigue siendo una fecha sin hora y una hora sin fecha sigue siendo una hora sin fecha, en vez de convertirse todo en un instante completo inventando la parte que faltaba. Ese cuidado existe porque la alternativa —usar la representación por defecto del lenguaje— producía un texto dependiente del idioma y del huso del visitante, distinto en tu máquina que en la nuestra.

Hay una arruga concreta que conviene conocer antes de comparar cadenas aguas abajo. Una hora local escrita en el TOML como las ocho de la mañana llega al JSON con una parte fraccionaria de milisegundos añadida. El valor no cambia; su representación textual sí.

Si lo que hay al otro lado interpreta la cadena como una hora, no pasa nada. Si lo que hay al otro lado la compara carácter a carácter con una constante escrita a mano —cosa mucho más frecuente en scripts de despliegue de lo que a nadie le gusta admitir—, ese sufijo es exactamente lo que va a romper la comparación, y el fallo aparecerá lejos de la conversión.

TOML 1.0 exige que una implementación maneje enteros con signo de 64 bits. Los números de JSON son de coma flotante de doble precisión y solo son exactos hasta unos nueve mil billones. Un TOML con un entero por encima de ese rango es completamente legal, y aquí el analizador se detiene con un error que dice que el valor entero no puede representarse sin pérdida, en lugar de producir un JSON con un número equivocado dentro.

Negarse es la decisión correcta y merece entenderse en vez de esquivarse a ciegas. Un identificador redondeado en silencio es un fallo que aparece semanas después en un cruce que no encuentra nada. Si tu TOML guarda un valor de ese tamaño —un identificador de los que generan los sistemas distribuidos, un número de serie largo, una marca de tiempo en nanosegundos como entero—, entrecomíllalo como cadena en el origen: nunca fue una cantidad, y entrecomillarlo deja correctos de golpe a todos los consumidores.

Los decimales de TOML incluyen `inf` y `nan` como valores literales. JSON no tiene ninguno de los dos, y el escritor pone `null` para ambos. Es lo que hace el serializador del lenguaje y es una pérdida que nadie reporta: un límite superior configurado como infinito y un límite superior sin configurar se vuelven la misma cosa en el JSON.

La pérdida más sutil es la de tipo. TOML distingue un entero de un decimal, de modo que `1` y `1.0` son valores distintos con tipos distintos y un esquema o una aplicación pueden apoyarse en ello. JSON tiene un único tipo numérico, y `1.0` se serializa como `1`. Si algo aguas abajo necesita saber que un valor se declaró como decimal, esa información tiene que viajar por otro camino, porque en el fichero ya no está.

Las tablas y las claves salen en el orden en que las declaró el TOML, lo cual mantiene el fichero convertido legible y hace que un diff entre dos conversiones signifique algo. Nada en este conducto de datos ordena alfabéticamente ni reorganiza por su cuenta.

La excepción son las claves numéricas. Una clave entrecomillada de TOML que sea un número —cosa que aparece en configuraciones que indexan por año o por puerto— se coloca por delante de todas las demás de su objeto y se ordena de menor a mayor, porque así ordena el lenguaje las claves con aspecto de entero. Es el único punto en el que el JSON no se lee en la misma secuencia que el origen.

Un TOML es UTF-8 por especificación, y buena parte de los que se escriben en español llevan texto acentuado en los valores: descripciones de paquete, nombres de autores, mensajes de ayuda. El escritor de este sitio no aplica ningún paso de escape a caracteres no ASCII, así que esos caracteres aparecen tal cual en el JSON en vez de convertirse en secuencias `\u00f1`.

Es lo que quiere casi todo el mundo, porque el fichero se sigue leyendo, y conviene saberlo si algo aguas abajo espera lo contrario. Un consumidor antiguo que asuma ASCII escapado no va a recibirlo, y ahí el arreglo es un paso de reescritura en el consumidor y no un ajuste aquí. Comprueba una descripción con tildes al principio, no al final del despliegue.

La salida va sangrada con dos espacios y termina en un salto de línea. No hay opción para cambiarlo, ni modo compacto, ni ordenación alternativa: es una sola forma de escribir el JSON, siempre la misma, que es precisamente la propiedad que hace comparable la salida de dos conversiones distintas.

Ese detalle importa más de lo que parece si el JSON acaba pasando por un control de versiones o por una comprobación de igualdad en la integración continua. Una salida estable convierte «el fichero ha cambiado» en una señal fiable; una salida que dependiera de un ajuste convertiría cada actualización en ruido.

TOML admite comentarios y los usa mucho: el motivo por el que una dependencia está fijada, el número de incidencia junto a un apaño, el bloque que explica a qué entorno se aplica un ajuste. JSON no tiene sintaxis de comentario, así que nada de eso llega.

Eso resuelve la dirección de la relación entre los dos ficheros. El TOML es el que la gente edita y revisa, y el JSON se genera a partir de él cada vez que algo necesita leerlo. Guardar el JSON en el repositorio junto al TOML crea dos versiones de la verdad que acabarán separándose; generarlo en el paso de compilación, no.

Si la lectura ocurre dentro de una aplicación y no en un paso de compilación, usa un analizador. Todos los lenguajes mayores tienen uno, y Python lleva varias versiones con uno en su biblioteca estándar. Leer el fichero directamente conserva los tipos temporales y la distinción entre entero y decimal que esta conversión aplana.

El conversor se gana su sitio en la frontera: una inspección puntual, un paso de integración continua donde añadir una dependencia cuesta más de lo que vale, o una tubería cuya siguiente etapa solo habla JSON. Todo ocurre en tu navegador y ninguna petición lleva el fichero fuera, así que una configuración privada con credenciales dentro se puede soltar aquí sin que salga de tu equipo. El tope son 100 MB por archivo, que ningún fichero de configuración se acerca a alcanzar.