YAML vs TOML

Dos filosofías: inferido frente a declarado

La diferencia más profunda es dónde vive la estructura. En YAML, la estructura es el espacio en blanco: los niveles de sangría definen el anidamiento, y los tabuladores están prohibidos sin más. En TOML, la estructura es la puntuación: una línea como [database.pool] declara una tabla, y la sangría es puramente cosmética. Todo lo demás en esta página —seguridad al pegar, verbosidad en profundidad, mensajes de error— se deriva de esa única decisión.

Sintaxis: sangría frente a cabeceras de tabla

La configuración superficial deja bien parados a ambos formatos; el anidamiento profundo los separa. YAML se vuelve cada vez más silencioso a medida que crece la estructura —dos espacios y un guion—, mientras que TOML escribe una cabecera por nivel: [database.pool.limits], luego [database.pool.limits.read]. A tres niveles, TOML es simplemente verboso; a ocho, YAML es la única opción cuerda para escribir a mano. Los arrays de tablas invierten el veredicto: los bloques [[products]] de TOML son nítidos y greppables, mientras que las listas largas de mapas en YAML son justo donde las columnas se desalinean.

La seguridad al pegar se deduce directamente. Soltar un bloque en YAML una columna más a la izquierda o a la derecha, o rompe el parseo o —peor— cambia en silencio lo que significa; el archivo sigue parseando y nada te avisa. En TOML, un bloque pegado lleva su propia [header], así que aterriza donde dice su cabecera sin importar el espacio en blanco de alrededor.

Tipos y el problema de Noruega

YAML infiere los tipos de los escalares, y la inferencia tiene dientes: yes, no, on y off se vuelven booleanos bajo las reglas de YAML 1.1 que muchos parsers aún traen de serie, NO se vuelve false, y una versión escrita 1.20 puede llegar como el número 1.2. YAML 1.2 recortó las reglas pero no unificó a los parsers, así que el mismo archivo puede recibir tipos distintos según la herramienta. La defensa es poner entre comillas todo lo que deba seguir siendo una cadena.

TOML no tiene un paso de inferencia que pueda fallar: las comillas hacen una cadena, los dígitos desnudos hacen un entero (se permiten guiones bajos para legibilidad), y las marcas de tiempo RFC 3339 son un tipo de primera clase —una ventaja genuina frente a JSON y YAML para configuración que lleva fechas—. Las cadenas multilínea existen en ambos: los bloques con triple comilla """ de TOML y los escalares | y > de YAML.

Ecosistemas y cuándo elegir cada uno

Los ecosistemas ya repartieron el territorio. YAML es dueño de lo cloud-native y del CI: manifiestos de Kubernetes, GitHub Actions y GitLab CI, Ansible, docker-compose, descripciones OpenAPI. TOML es dueño del empaquetado y de los metadatos de herramientas: el Cargo de Rust, el pyproject.toml de Python, y una larga lista de herramientas CLI que quieren configuración inequívoca y amable con los comentarios. Elegir contra un ecosistema significa pelearse para siempre con sus herramientas, así que rara vez es una elección libre.

Donde sí eliges: YAML para documentos profundamente anidados y revisados por personas, y TOML cuando los valores deben ser inequívocos, los diffs exactos y los archivos editados tanto por personas como por generadores. La recomendación se invierte con regularidad —la mayoría de los repositorios tienen ambos— y los conversores enlazados aquí tienden puentes en ambas direcciones localmente.