Formato TOML: Guía Completa sobre Tom's Obvious Minimal Language

¿Qué es TOML?

TOML son las siglas de Tom's Obvious Minimal Language (El Lenguaje Mínimo Obvio de Tom), creado por Tom Preston-Werner (cofundador de GitHub) en 2013. TOML está diseñado como un formato de archivo de configuración que es fácil de leer y escribir gracias a una semántica obvia, mientras se mapea de forma inequívoca a una estructura de datos de tabla hash (diccionario clave-valor).

La filosofía de TOML contrasta explícitamente con el enfoque de YAML: donde YAML maximiza la expresividad a costa de una especificación compleja y errores de análisis, TOML minimiza la ambigüedad a costa de una expresividad reducida. El resultado es un formato familiar (similar a los archivos INI), con inferencia de tipos inequívoca, que puede ser analizado por una implementación simple y pequeña.

Los principales adoptantes incluyen Rust (Cargo.toml para manifiestos de paquetes), Python (pyproject.toml para metadatos de proyectos y configuración de herramientas), Hugo (configuración del sitio) y muchas otras herramientas modernas de desarrollo.

Sintaxis Principal

# Esto es un comentario TOML

titulo = "Ejemplo de Configuración TOML"
version = "1.0.0"
fecha_lanzamiento = 2024-01-15

[servidor]
host = "localhost"
puerto = 8080
depuracion = false

[servidor.ssl]
habilitado = true
cert = "/etc/ssl/cert.pem"
clave = "/etc/ssl/clave.pem"

[base_datos]
url = "postgresql://usuario:pass@localhost:5432/mibd"
max_conexiones = 100
tiempo_espera = 30.0

[caracteristicas]
habilitadas = ["busqueda", "auth", "api"]
deshabilitadas = []

Reglas de sintaxis clave:

• clave = valor para asignaciones
• [tabla] para secciones
• [[array_de_tablas]] para arrays de tablas
• Comentarios # hasta el final de la línea
• Sin conversión implícita de tipos — los tipos son explícitos desde la sintaxis literal

Tipos de Datos

TOML define los siguientes tipos con sintaxis literal inequívoca:

Tipos de cadena:

• "cadena básica" — procesa secuencias de escape
• 'cadena literal' — SIN procesamiento de escape
• """multilínea básica""" — varias líneas con escape
• '''multilínea literal''' — varias líneas sin escape

Tipos de fecha/hora (la característica estrella de TOML frente a JSON):

creado_en = 2024-01-15T10:30:00Z        # Datetime con desplazamiento (RFC 3339)
dt_local = 2024-01-15T10:30:00          # Datetime local (sin desplazamiento)
fecha_local = 2024-01-15                # Solo fecha
hora_local = 10:30:00                   # Solo hora

Tablas y Anidamiento

Las tablas son el equivalente TOML de los objetos JSON/asignaciones YAML. Definen un nuevo espacio de nombres:

[propietario]
nombre = "Tom Preston-Werner"
nacimiento = 1979-05-27

[base_datos]
servidor = "192.168.1.1"
puertos = [8001, 8001, 8002]
max_conexiones = 5000
habilitado = true

Las claves con punto proporcionan una forma alternativa de expresar el anidamiento en línea:

[servidor]
host = "localhost"
puerto = 8080
ssl.habilitado = true
ssl.cert = "/etc/cert"

Arrays de Tablas

La sintaxis [[]] crea arrays de tablas — la característica más potente de TOML:

[[servidores]]
nombre = "alpha"
ip = "10.0.0.1"
rol = "frontend"

[[servidores]]
nombre = "beta"
ip = "10.0.0.2"
rol = "backend"

TOML frente a YAML frente a INI frente a JSON

La ventaja clave de TOML sobre YAML: Sin sangría significativa, sin ambigüedad de tipos (los booleanos yes/no/on/off de YAML), sin riesgo de ejecución de código arbitrario, especificación más simple.

TOML en Proyectos Reales

Cargo.toml de Rust:

[package]
name = "mi-crate-increible"
version = "0.1.0"
edition = "2021"

[dependencies]
serde = { version = "1.0", features = ["derive"] }
tokio = { version = "1", features = ["full"] }

[[bench]]
name = "mi_benchmark"
harness = false

pyproject.toml de Python:

[build-system]
requires = ["setuptools>=68", "wheel"]

[project]
name = "mi-paquete"
version = "1.0.0"
requires-python = ">=3.11"
dependencies = [
    "requests>=2.28",
    "click>=8.0",
]

[tool.pytest.ini_options]
testpaths = ["tests"]

Análisis de TOML

Python (tomllib — biblioteca estándar desde Python 3.11):

import tomllib

with open("pyproject.toml", "rb") as f:  # Nota: modo binario rb
    config = tomllib.load(f)

print(config["project"]["name"])

Para Python 3.10 y anteriores: pip install tomli y usar tomli.load().

Conversión de TOML

TOML → JSON: Biblioteca toml de Python + json.dumps(). Casi sin pérdida para la mayoría de los datos; los tipos datetime se convierten en cadenas.

TOML → YAML: Mediante Python: yaml.dump(tomllib.load(open("config.toml", "rb"))).

JSON → TOML: Más complejo — los arrays JSON de objetos heterogéneos pueden no mapearse limpiamente a los [[tablas]] tipados de TOML.

Resumen

TOML ocupa un punto óptimo entre los archivos INI (familiares pero limitados) y YAML (potente pero complejo). Su sistema de tipos inequívoco, el soporte nativo de datetime, la sintaxis legible de [tabla] y [[array de tablas]], y la falta de sensibilidad al espacio en blanco lo hacen ideal para archivos de configuración centrados en el desarrollador. Los ecosistemas de Rust y Python se han estandarizado en TOML para la configuración de proyectos (Cargo.toml y pyproject.toml respectivamente), consolidando su posición como formato de configuración de primera clase. Para pipelines CI/CD e infraestructura donde los anclajes DRY de YAML son valiosos, YAML sigue siendo la mejor opción; para manifiestos de paquetes y configuración de aplicaciones, la claridad de TOML gana.

Conversiones relacionadas

Conversiones frecuentes del catálogo:

• JPG a PNG
• MP4 a MP3
• PDF a DOCX
• PNG a JPG
• MP3 a WAV
• DOCX a PDF