Conversor de JSON a TOML

El JSON es el formato estándar para intercambiar datos entre aplicaciones, con su sintaxis de objetos y arrays entre llaves y corchetes. El TOML, cuyo nombre significa Tom's Obvious, Minimal Language, está pensado para archivos de configuración legibles por personas, con secciones claras y pares clave-valor sencillos.

Convertir de JSON a TOML significa reescribir esa misma información en una sintaxis más amable para configurar herramientas. Lo usan proyectos como Cargo de Rust, Poetry de Python con su pyproject.toml y el generador de sitios Hugo.

La diferencia estructural principal es de estilo: el JSON anida con llaves, mientras que el TOML usa tablas marcadas con corchetes y una indentación visual mínima. Un objeto JSON se convierte en una tabla TOML, y un array de objetos en un array de tablas. Si después quieres revisar o limpiar el JSON de partida, el formateador de JSON te lo deja ordenado antes de convertir.

El conversor empieza analizando el JSON de entrada y comprobando que sea válido. Una vez interpretada la estructura, recorre cada clave y la traduce a la sintaxis TOML correspondiente.

Los objetos se convierten en tablas, identificadas con su nombre entre corchetes. Los objetos anidados generan tablas con nombre compuesto, separando los niveles con puntos. Un array de objetos se transforma en un array de tablas, una construcción propia de TOML que repite la cabecera entre dobles corchetes por cada elemento.

Los valores simples, como cadenas, números y booleanos, se escriben directamente como pares clave-valor. Las estructuras pequeñas pueden representarse con tablas en línea para mantener el archivo compacto. Las fechas en formato ISO se reconocen como valores datetime nativos de TOML.

Los casos límite, como claves con caracteres especiales que necesitan comillas o valores nulos que TOML no admite directamente, se gestionan con reglas claras para que el resultado siga siendo válido.

El motivo más frecuente para convertir JSON a TOML es crear archivos de configuración. Si tienes los ajustes de un proyecto en JSON y la herramienta de destino espera TOML, la conversión te ahorra reescribirlo a mano.

En el ecosistema de Rust, el archivo Cargo.toml define dependencias y metadatos del proyecto. En Python, pyproject.toml cumple un papel parecido para Poetry y pip. Generar estos archivos a partir de datos JSON resulta cómodo cuando los produce un script o una plantilla.

Hugo, el generador de sitios estáticos, también usa TOML para su configuración, de modo que puedes partir de ajustes en JSON y obtener el formato que espera.

En general, la conversión sirve como migración entre formatos de configuración y como puente en el intercambio de datos entre sistemas. Para el camino inverso tienes el conversor de TOML a JSON, y si trabajas con YAML, el conversor de JSON a YAML cubre esa otra ruta.

Entender cómo TOML organiza los datos ayuda a leer el resultado de la conversión. Una tabla es una sección con nombre entre corchetes que agrupa pares clave-valor, equivalente a un objeto JSON. Cuando hay anidamiento, el nombre de la tabla incluye los niveles separados por puntos.

Los arrays de tablas son la forma de TOML de representar una lista de objetos. Cada elemento se introduce con su nombre entre dobles corchetes, y los elementos se repiten en orden. Es la traducción natural de un array JSON lleno de objetos.

Las tablas en línea, escritas entre llaves en una sola línea, son útiles para estructuras pequeñas que no merecen una sección aparte. TOML también distingue tipos de forma nativa: cadenas, enteros, decimales, booleanos y fechas con hora.

Esta riqueza de tipos es una ventaja frente al JSON, donde una fecha siempre es texto. Por eso una cadena ISO en el JSON de origen puede convertirse en un valor datetime real en el TOML resultante, más expresivo y fácil de validar.

Antes de convertir, valida que el JSON de entrada esté bien formado. Una llave o coma fuera de lugar impide el análisis, así que conviene revisarlo primero con el formateador de JSON para detectar errores de sintaxis.

Ten en cuenta que TOML no admite valores nulos. Si tu JSON contiene campos con null, decide si quieres omitirlos o sustituirlos por una cadena vacía antes de la conversión, porque no tienen un equivalente directo.

Revisa también las claves. TOML permite nombres sencillos sin comillas, pero las claves con espacios, puntos o caracteres especiales deben ir entre comillas en el resultado. Mantener nombres limpios en el JSON facilita un TOML más legible.

Por último, comprueba el archivo generado en su herramienta de destino. Un pyproject.toml o un Cargo.toml deben cumplir convenciones concretas más allá de la sintaxis, como nombres de sección esperados. La conversión te da una base válida, pero la estructura final depende de lo que cada herramienta requiera.