TOML vs YAML vs JSON — Formatos de configuración clasificados por cuánto les molestarán

Cada proyecto eventualmente te obliga a elegir un formato de configuración. YAML está por todas partes. JSON es más antiguo que algunos de tus compañeros. TOML apareció recientemente con la mano levantada diciendo: «de hecho, fui diseñado para esto». Todos los tres te traicionarán eventualmente. Las traiciones son solo diferentes.

Aquí tienes una comparación directa — la misma configuración, tres formatos — seguida de exactamente cuándo cada uno te hará arrepentido de tus decisiones de vida.

La Misma Configuración, Tres Maneras

Una configuración básica para una aplicación web: nombre, puerto, bandera de depuración, cadena de versión, configuración de la base de datos, orígenes permitidos. Nada exótico. Aquí comienzan las diferencias entre los formatos.

TOML

# App configuration
[app]
name = "my-app"
port = 3000
debug = false
version = "1.2.3"
allowed_origins = ["https://example.com", "https://api.example.com"]

[database]
host = "localhost"
port = 5432
name = "mydb"

YAML

# App configuration
app:
  name: my-app
  port: 3000
  debug: false
  version: "1.2.3"
  allowed_origins:
    - https://example.com
    - https://api.example.com

database:
  host: localhost
  port: 5432
  name: mydb

JSON

{
  "app": {
    "name": "my-app",
    "port": 3000,
    "debug": false,
    "version": "1.2.3",
    "allowed_origins": [
      "https://example.com",
      "https://api.example.com"
    ]
  },
  "database": {
    "host": "localhost",
    "port": 5432,
    "name": "mydb"
  }
}

Al Aviso

Característica	TOML	YAML	JSON
Comentarios	✅ Sí	✅ Sí	❌ No
Inferencia de tipos	Explicita	Agresiva (a menudo incorrecta)	Explicita
Matrices	= ["a", "b"]	- item o inline	["a", "b"]
Comas finales	N / A	N / A	❌ Ilícita
Configuraciones profundamente anidadas	Se vuelve muy extensa	Leible de forma aproximada	Extensa pero sin ambigüedad
Estabilidad del esquema	TOML 1.0 (2021, estable)	Diferencias entre versiones 1.1 y 1.2 en el parser	Estable
Soporte para valores nulos	❌ Sin tipo nulo	✅ Sí (~ o null)	✅ Sí (null)
Uso común	Cargo.toml, pyproject.toml	GitHub Actions, k8s, Docker	package.json, tsconfig.json

YAML: Más legible hasta que ya no lo es

YAML se ve bien en presentaciones. Una configuración plana se lee casi como un texto. El problema comienza cuando se enfrentas a uno de sus casos límite — y en ese momento ya tu archivo de configuración es infraestructura crítica.

El Problema de Noruega

En YAML 1.1 — que la mayoría de los analizadores aún usan por defecto — estos valores son todos booleanos: y, n, yes, no, on, off, true, false. Así que country: NO se analiza como country: false. Esta es la verdadera razón por la que se llama el Problema de Noruega — el código de país de Noruega es NO. PyYAML lo solucionó en la versión 6.0 (lanzada en 2022). SnakeYAML (usado por muchas herramientas en Java) aún no ha resuelto completamente este problema. Revisa tu analizador antes de usar valores sin comillas en tus configuraciones. no o yes en valores de configuración.

Inferencia de tipos que adivina mal

Los valores no entrecomillados en YAML se convierten en tipos. port: 8080 se convierte en un entero. version: 1.10 se convierte en un número decimal 1.1 — matemáticamente iguales, pero semánticamente incorrectos. Si olvidas colocar comillas en una cadena de versión, pasarás diez minutos preguntándote por qué tu aplicación piensa que está en v1.1 en lugar de v1.10. La solución es aburrida: coloca comillas en todo lo que debería permanecer como cadena. Pero YAML no te obliga a hacerlo, así que no lo hace.

La sangría es crítica

Los espacios en tabuladores son ilegales en YAML — no se recomiendan, son ilegales. Si mezclas sangrías de dos espacios y cuatro espacios dentro de un archivo, obtienes un error de análisis que a menudo señala la línea incorrecta. GitHub Actions es el punto más agudo aquí: un bloque mal sangrado falla en tiempo de ejecución, no en tiempo de análisis, porque los ejecutores de workflows solo validan la sintaxis, no la estructura de pasos. Obtendrás un mensaje de «valor inesperado» de una tarea de CI sin indicación de cuál paso falló, y pasarás 20 minutos agregando salida de depuración antes de darte cuenta de que el problema era una sangría de dos espacios donde se esperaba cuatro. run: el bloque falla en tiempo de ejecución, no en tiempo de análisis, porque los ejecutores de flujo solo validan la sintaxis, no la estructura de pasos. Obtendrás un mensaje de "valor inesperado" desde una tarea de CI sin indicación de cuál paso falló, y pasarás 20 minutos agregando salida de depuración antes de darte cuenta de que el problema era un tabulador de dos espacios donde se esperaba cuatro.

Si tu YAML se ha convertido en una mezcla de sangrías inconsistentes, el Formateador de YAML lo normalizará antes de que comiences a depurar.

TOML: El formato que realmente pensó en la configuración

Tom Preston-Werner (co-fundador de GitHub) creó TOML porque estaba cansado de escribir configuraciones en estilo INI con comportamientos de análisis inconsistentes y configuraciones en YAML que lo sorprendían. TOML 1.0 llegó en enero de 2021 tras años de revisiones. Ahora es el estándar para proyectos en Rust (Cargo.toml), para el empaquetado en Python (pyproject.toml) y para sitios de Hugo. El esquema es estable, los analizadores son consistentes y el sistema de tipos hace lo que esperas.

Lo que hace bien

• Sin coerciones inesperadas. version = "1.10" Siempre es una cadena. port = 3000 Siempre es un entero. Lo que escribes es lo que obtienes.
• Los comentarios funcionan exactamente como esperas (# al final de la línea), a diferencia de JSON.
• Las configuraciones planas hasta moderadamente anidadas son realmente legibles, a diferencia de JSON profundamente anidado.

La sintaxis de array de tablas

La principal dificultad de TOML es su sintaxis de array de tablas. Si quieres un array de objetos — por ejemplo, múltiples conexiones a bases de datos — la notación se ve así:

[[databases]]
name = "primary"
host = "db1.example.com"

[[databases]]
name = "replica"
host = "db2.example.com"

recibe una parte igual del espacio restante tras restar el espacio de separación. Tres columnas de [[double bracket]] sección es un elemento en el databases array. Funciona. Es inambiguo. Pero cada desarrollador que abre un archivo TOML por primera vez pregunta: «¿es esto INI?» — porque se ve así. Esa inquietud tiene un costo real cuando estás incorporando contribuyentes que nunca han visto TOML antes.

TOML también no tiene null tipo — intencionalmente. Si tu esquema utiliza nulo para indicar que una clave está presente pero explícitamente no establecida, necesitarás modelarlo de forma diferente (omitir la clave por completo o usar un valor sentinela). Y las configuraciones profundamente anidadas se vuelven extensas rápidamente: TOML no tiene el sistema de anclajes/alias de YAML para reutilizar subárboles, así que hay mucho copiar y pegar si tu configuración tiene estructuras repetidas.

El Formateador de TOML es útil cuando estás tratando de limpiar un archivo TOML que ha crecido de forma orgánica con el tiempo.

JSON: El demonio que conoces

JSON fue diseñado para el intercambio de datos — máquinas hablando entre máquinas — no para que los humanos escriban archivos de configuración. Al final, se convirtió en un formato de configuración porque cada lenguaje ya tenía un analizador de JSON, y esa conveniencia ganó. Ahora tenemos package.json, tsconfig.json, .eslintrc.json y aproximadamente 40 otros archivos de configuración en cada proyecto de JavaScript, todos editados a mano.

Sin comentarios. Aún.

Douglas Crockford eliminó los comentarios de JSON intencionalmente en 2012 — temía que los desarrolladores los utilizaran como directivas de análisis (similar a los comentarios condicionales de IE). El internet ha reclamado esto todos los días desde entonces. Las soluciones que usan las personas:

• JSONC — JSON con comentarios. VS Code lo usa para settings.json y launch.json. No es parseable por analizadores estándar de JSON. No estándar.
• JSON5 — añade comentarios, comas finales, claves sin comillas, cadenas multilineales. Tiene un esquema y un analizador independiente. Babel lo usa para configuraciones. Aún no es JSON estándar.
• A "_comment" llave — un campo de cadena que contiene el texto del comentario. Funciona. Se ve ridículo. Se introduce en tu modelo de datos.

Comas al final

También ilegal. Añade una coma final al último elemento de un array o objeto y JSON.parse lanza SyntaxError: Unexpected token } — diciéndote que hay un problema, pero no indicando dónde está la coma errónea. Este es el error de análisis número uno en archivos de configuración escritos por humanos, y ocurre porque cada otro lenguaje moderno (arrays en JavaScript, listas en Python, enumeraciones en Rust) permite comas finales y los humanos escriben JSON a mano con esos hábitos.

Lo que JSON hace bien

El sistema de tipos es inambiguo y universal. Cada analizador de JSON en cada lenguaje está de acuerdo en lo que true, 1, "1"y null significa. JSON Schema es la opción de validación de configuración más madura de las tres — VS Code lo utiliza para validar tsconfig.json y package.json en tiempo real, con resaltado de errores en línea. Cuando las herramientas generan tu JSON (webpack, tsc, npm), no te importa la legibilidad — eso es lo que hace el Formateador JSON para.

Conclusión: Elige según el contexto, no según la preferencia

Usa JSON cuando las herramientas generan o consumen el archivo (package.json, tsconfig, configuraciones de AWS, respuestas de la API de GitHub), o cuando necesitas validación mediante JSON Schema. No lo escribas a mano más de lo necesario. La falta de comentarios es un problema, pero la ubiquidad y el soporte de herramientas son difíciles de discutir.

Usa YAML cuando la configuración es principalmente escrita por humanos y es relativamente plana — workflows de GitHub Actions, archivos de Docker Compose, manifestos de Kubernetes. Coloca comillas en cualquier valor que podría ser mal interpretado como un booleano o un número (cadenas de versión, códigos de país, cualquier valor que comience con un dígito). Ejecuta un linter. Nunca uses tabuladores. Trata la inferencia de tipos como un error, no como una característica.

Usa TOML cuando controlas la elección del formato y deseas evitar coerciones inesperadas de tipos. Es el más honesto de los tres sobre lo que es. Si estás iniciando un proyecto de cero y ninguna herramienta exige un formato, TOML es el menos probable que te sorprenda seis meses después. La inquietud es un costo único; la claridad es permanente.

También te puede interesar