En este artículo
¿Qué es TOML?
TOML (Tom's Obvious, Minimal Language) es un formato de archivo de configuración diseñado para ser fácil de leer y escribir. Creado por Tom Preston-Werner (cofundador de GitHub), TOML se mapea claramente a una tabla hash y está destinado a ser inequívoco — cada documento TOML tiene exactamente una interpretación válida.
TOML es el formato de configuración preferido para Rust (Cargo.toml), Python (pyproject.toml) y muchos generadores de sitios estáticos. Admite comentarios, literales de fecha y hora y tablas anidadas, permaneciendo más simple que YAML y más legible para humanos que JSON.
Reglas de sintaxis TOML
La sintaxis de TOML está diseñada para ser mínima e inequívoca. Estos son los elementos fundamentales del lenguaje.
- Pares clave/valor — el bloque de construcción básico, escrito como clave = valor en cada línea. Las claves pueden ser simples (sin comillas), entre comillas o con puntos para acceso anidado.
- Tablas — secciones definidas con encabezados [nombre_tabla] que agrupan pares clave/valor relacionados. Las tablas pueden anidarse usando claves con puntos o la sintaxis [[array_de_tablas]].
- Arrays — listas ordenadas definidas con corchetes [1, 2, 3]. Todos los elementos deben ser del mismo tipo. Los arrays multilínea están permitidos con comas finales.
- Literales de fecha y hora — TOML admite nativamente fechas RFC 3339 como 2026-03-15T14:30:00Z, fechas locales (2026-03-15), horas locales (14:30:00) y desplazamientos de fecha y hora.
- Cadenas multilínea — las cadenas entre comillas triples ("""texto""") preservan los saltos de línea y permiten contenido largo sin secuencias de escape. Las cadenas literales usan comillas simples ('no\escape').
Patrones TOML comunes
TOML se usa ampliamente en archivos de configuración de proyectos en diferentes ecosistemas.
- Cargo.toml — el gestor de paquetes de Rust usa TOML para metadatos del proyecto, dependencias, perfiles de compilación y configuración del espacio de trabajo
- pyproject.toml — la configuración del sistema de compilación moderno de Python, definida por PEP 517/518, reemplaza setup.py y setup.cfg con un archivo TOML estandarizado
- Configuración de Hugo — el generador de sitios estáticos Hugo usa TOML (o YAML/JSON) para la configuración del sitio, incluyendo temas, menús, taxonomías y ajustes de compilación
- Configuración de Netlify — netlify.toml configura comandos de compilación, reglas de redireccionamiento, variables de entorno y contextos de despliegue para sitios de Netlify
Pruébalo gratis — sin registro
Validar TOML en linea →Errores de validación comunes
TOML es estricto por diseño — muchos errores que YAML aceptaría silenciosamente fallarán en TOML. Estos son los problemas de validación más comunes.
- Claves duplicadas — TOML prohíbe definir la misma clave dos veces en la misma tabla. Esto incluye las claves establecidas mediante notación de puntos y encabezados de tabla normales.
- Formato de fecha no válido — TOML requiere fechas RFC 3339. Los errores comunes incluyen omitir el separador T (2026-03-15 14:30:00 en lugar de 2026-03-15T14:30:00) o usar barras en lugar de guiones.
- Tipos de array mixtos — todos los elementos en un array TOML deben ser del mismo tipo. [1, "dos", 3] es inválido porque mezcla enteros y cadenas.
- Cadenas sin cerrar — olvidar cerrar una cadena entre comillas o usar el tipo de comilla incorrecto causa errores de análisis. Preste atención a las comillas triples sin correspondencia en cadenas multilínea.
TOML vs YAML vs JSON
Cada formato tiene fortalezas que lo hacen más adecuado para ciertos casos de uso.
- Legibilidad — TOML y YAML son altamente legibles para humanos. TOML usa sintaxis explícita (corchetes, signos de igual) mientras que YAML depende de la indentación. JSON es menos legible para configuración debido a las comillas requeridas y la ausencia de comentarios.
- Rigidez — TOML es el más estricto de los tres. Rechaza construcciones ambiguas y no tiene coerción de tipos implícita. La flexibilidad de YAML (yes/no como booleanos, cadenas sin comillas) a menudo causa comportamientos inesperados.
- Comentarios — tanto TOML como YAML admiten comentarios (TOML usa #, YAML usa #). JSON no tiene soporte de comentarios en absoluto, lo que lo hace menos adecuado para archivos de configuración que necesitan documentación.
Preguntas frecuentes
¿Cómo funcionan las tablas anidadas en TOML?
TOML admite tablas anidadas mediante dos mecanismos: claves con puntos (a.b.c = valor) y encabezados de tabla ([padre.hijo]). Ambos crean la misma estructura anidada. Para arrays de tablas (como múltiples dependencias de paquetes), use corchetes dobles ([[nombre_array]]). Cada bloque [[nombre_array]] agrega un nuevo elemento al array.
¿Cuáles son las diferencias entre TOML v1.0 y versiones anteriores?
TOML v1.0 (lanzado en enero de 2021) es la primera versión estable. Los cambios clave respecto a los borradores pre-1.0 incluyen el manejo clarificado de fechas y horas, la semántica formalizada de tablas inline y el comportamiento refinado de arrays de tablas. La mayoría de las herramientas modernas usan TOML v1.0 — si está escribiendo nuevos archivos de configuración, apunte a la v1.0.
¿Cómo convierto YAML a TOML?
YAML y TOML tienen diferentes modelos de datos, por lo que la conversión no siempre es uno a uno. Las estructuras simples de clave-valor y los objetos anidados se convierten directamente. Las características de YAML como anclas, alias y claves complejas no tienen equivalente en TOML. Para la mayoría de los archivos de configuración, la conversión es sencilla — mapee los diccionarios YAML a tablas TOML y las listas YAML a arrays TOML.