Convertir JSON a TOML

El JSON no admite comentarios. Está escrito en la especificación, no es un descuido, y es la razón principal de que mantener configuración en JSON resulte incómodo: el motivo por el que un tiempo de espera son 45 segundos no puede vivir al lado del 45. El TOML sí los admite, y esa suele ser toda la motivación de esta conversión.

El segundo motivo es la planitud. Un JSON de configuración con tres niveles son tres niveles de llaves y mucha sangría; lo mismo en TOML es una línea de cabecera y una lista corta de claves debajo. Los datos no han cambiado, pero el diff que ve quien revisa el cambio de un valor es una línea en vez de un bloque resangrado.

Un documento TOML es una tabla. No puede empezar por una lista como sí puede un documento JSON, así que un archivo cuyo primer carácter es un corchete no tiene nada sobre lo que proyectarse. La conversión no falla: cualquier valor que no sea un objeto se envuelve bajo una clave llamada items, y la salida arranca con bloques repetidos de esa clave.

Eso mantiene el archivo válido y es un marcador de posición, no una respuesta. Ningún conversor puede saber si la herramienta que va a leerlo espera que esa lista se llame dependencies, servers o plugins. Cambia el nombre en la primera línea y el resto del archivo ya está bien: es una edición de una palabra, y está pensada para que se vea en lugar de esconderse.

Este es el fallo que conviene comprobar siempre. El TOML no tiene literal nulo y el escritor no se inventa ninguno: una clave cuyo valor en JSON era nulo simplemente no se escribe. Convierte un documento con una sola clave nula y la salida es un archivo vacío. Convierte una tabla con una clave real y otra nula y solo aparece la real.

Que eso importe depende por completo de la herramienta que lea el resultado. Muchos analizadores de configuración tratan igual una clave ausente y una clave nula —ambas caen en el valor por defecto— y ahí no se ha perdido nada. Otros las distinguen, y ahí la conversión ha cambiado la configuración en silencio. La defensa es buscar nulos en el JSON antes de convertir y no comparar los dos archivos después, porque una línea que falta es mucho más difícil de ver que una línea distinta.

Esta es la parte que sorprende a quien esperaba que el TOML fuera un formato más pobre que el JSON. Una lista de registros se expresa repitiendo la misma cabecera entre dobles corchetes: tres bloques con el mismo nombre son tres servidores, cada uno con sus claves debajo. Es más largo que una lista de JSON y bastante más fácil de editar, porque añadir un cuarto servidor es copiar cinco líneas en lugar de cuadrar corchetes.

Los miembros no tienen por qué coincidir. Una lista en la que el primer objeto tiene identificador y nombre y el segundo añade una región se convierte sin protestar y el TOML sigue siendo válido: cada bloque lleva las claves que tiene. Es una ventaja real frente a los destinos tabulares de este sitio, donde una lista heterogénea hay que reconciliarla en un único juego de columnas antes de escribir nada.

Una cabecera de tabla en TOML se apropia de todo lo que se escriba por debajo hasta la siguiente cabecera. Eso significa que una clave suelta colocada después de una cabecera pertenece a esa tabla, quisiera o no quisiera su autor. Por eso el escritor sube todos los valores sueltos de primer nivel por encima de la primera cabecera: un objeto con una tabla y un booleano al lado sale con el booleano arriba, una línea en blanco, y luego la tabla.

La salida no está, por tanto, en el orden en que estaba tu JSON, y no puede estarlo. Es la única reordenación que conserva el significado, y cualquier otra cambiaría a qué tabla pertenece una clave. Si la agrupación original importaba por legibilidad, recupérala moviendo bloques de tabla enteros —eso es seguro— y no claves sueltas por encima o por debajo de una cabecera.

Un JSON con cuatro niveles de objetos se convierte en una línea de cabecera con los nombres separados por puntos y la clave final debajo. El TOML expresa la profundidad en la cabecera y no en la sangría, que es la razón de que una configuración muy estructurada suela salir más corta y más plana de lo que era en JSON.

También tiene un límite, que es de gusto y no de validez. Una cabecera de cinco segmentos es legal y no la disfruta nadie. Si el archivo convertido tiene cabeceras de más de tres o cuatro tramos, suele ser señal de que la configuración pide dividirse en archivos o en herramientas distintas, y la conversión no ha hecho más que volver visible un problema que ya estaba.

La salida no lleva ni un comentario, porque la entrada no tenía dónde guardarlos. El JSON no los transporta, así que no hay nada que traducir: no es una carencia del conversor, es exactamente el motivo por el que valía la pena salir del JSON.

Eso convierte los cinco minutos siguientes a la conversión en la parte más aprovechable del ejercicio. El archivo TOML es la versión de esta configuración capaz de sostener lo que se sabe sobre ella: qué valores se pueden tocar sin miedo, cuál tiene que coincidir con otro de otro repositorio, por qué un límite está donde está. Hoy ese conocimiento vive en la cabeza de alguien o en un mensaje de commit, y este es el único momento en que escribirlo en el archivo no cuesta nada.

El TOML tiene cuatro tipos de fecha y hora, incluida una fecha con desfase horario que es un valor de primera clase y no una cadena. El JSON no tiene ninguno: da cadenas, números, booleanos, nulos, listas y objetos, y toda marca de tiempo de todo archivo JSON del mundo es una de las dos primeras cosas por convención.

Así que un valor JSON con una fecha en formato ISO se escribe como una cadena TOML entrecomillada, lo cual es correcto y no es lo que el formato sabría expresar. Si la herramienta que va a leerlo quiere una fecha de verdad, quita las comillas a mano en esas líneas. Después se interpreta como fecha y no hay que cambiar nada más en el archivo.

La comprobación más barata es un viaje de ida y vuelta: convierte el TOML otra vez a JSON y compáralo con el que tenías. Deberían faltar las claves que valían nulo y nada más, lo cual transforma una inquietud difusa en un diff que se lee en unos segundos.

La segunda comprobación es la propia herramienta. Cargo, Hugo y casi todo el empaquetado de Python te dicen enseguida si el documento se interpreta y si las claves están donde ellos las esperan, y eso detecta lo único que un viaje de ida y vuelta no puede detectar: un archivo perfectamente convertido cuya clave de primer nivel se sigue llamando items porque nadie la renombró.

En esta pestaña, en tu procesador. Las dos mitades son JavaScript —el lector de JSON es el del propio navegador y el escritor de TOML es una biblioteca pequeña que se carga bajo demanda—, así que ninguna petición lleva el archivo a ningún sitio, y no hay cuenta, ni cola, ni cupo diario. El tope es de 100 MB por archivo, que en configuración no lo alcanza nadie.

Aquí eso pesa más que en otros tipos de datos. Un archivo de configuración en JSON es justo lo que suele contener nombres de servidores internos, nombres de buckets, cuentas de servicio y de vez en cuando una credencial que alguien pensaba quitar, y subirlo a un conversor web es la parte que de verdad incumpliría una política. Aquí no hay nada que subir.