JSON vs YAML vs TOML: cuál usar y cuándo

Tres formatos, un mismo error

JSON, YAML y TOML no son intercambiables. Se parecen lo suficiente para que los ingenieros los intercambien por costumbre, y luego pasen una tarde explicando por qué se rompió el deploy.

JSON es para hablar entre máquinas. YAML es para humanos escribiendo configs. TOML es el punto medio sin sorpresas que cogió fuerza cuando los otros dos enseñaron sus límites. Cada uno tiene un trabajo, elegir el correcto es media batalla.

De un vistazo

JSON: el formato de cable

JSON es como se ven los datos en la red. Cada API del mundo habla JSON, cada navegador lo parsea de forma nativa, cada base de datos lo importa y lo exporta.

{
  "nombre": "María",
  "edad": 32,
  "skills": ["python", "sql"]
}

Sintaxis estricta. Sin comentarios. Sin comas finales. Las cadenas siempre entre comillas dobles. La estricción es el punto: hay exactamente una forma de escribir cada valor, así que dos parsers siempre están de acuerdo en lo que ven.

JSON es la elección correcta para:

• APIs máquina a máquina.
• Exportación e importación de datos.
• Formatos de almacenamiento que tienen que ir y volver limpios.
• Cualquier sitio donde el peso del parser importa (cada lenguaje tiene JSON en la librería estándar).

JSON es la elección incorrecta para archivos editados por humanos. La falta de comentarios sola lo hace doloroso para cualquier archivo de configuración que alguien va a leer una vez al año. El formateador JSON de AldeaCode es útil cuando recibes un blob JSON minificado y necesitas leerlo.

YAML: el formato humano que muerde

YAML deja a los humanos escribir configs sin entrecomillar cadenas ni preocuparse de comas. La indentación define la estructura, los comentarios están permitidos, y el archivo parece un esquema limpio.

nombre: María
edad: 32
skills:
  - python
  - sql

El precio es que YAML no es un formato simple. El spec 1.2 son cientos de páginas, y la mayoría de parsers implementan subconjuntos distintos. El “problema de Noruega” es el famoso: escribir pais: NO parsea como pais: false porque YAML 1.1 trata NO como un booleano. Hay docenas de gotchas similares.

YAML es la elección correcta para:

• Manifiestos de Kubernetes, donde el ecosistema lo espera.
• Pipelines de CI/CD (GitHub Actions, GitLab CI), por la misma razón.
• Configs largas editadas por humanos donde los comentarios y la indentación ayudan.

YAML es la elección incorrecta para:

• Cualquier cosa donde dos parsers pudieran no estar de acuerdo en el significado.
• Intercambio de datos entre sistemas escritos en lenguajes distintos.
• Archivos donde un error de copy paste puede cambiar silenciosamente un booleano por una cadena.

La regla más útil sobre YAML: fija la versión del spec, valida tu archivo con el mismo parser que producción, y no te fíes nunca de la intuición sobre cómo parsea un valor.

TOML: el medio que no sorprende

TOML lo diseñó el fundador de GitHub por frustración con YAML. El objetivo era simple: legible para humanos, sin conversiones implícitas, sin sensibilidad a espacios, una forma obvia de escribir cada cosa.

nombre = "María"
edad = 32
skills = ["python", "sql"]

[direccion]
ciudad = "Madrid"
cp = "28001"

Las secciones ([direccion]) reemplazan el anidamiento profundo. Las cadenas siempre van entrecomilladas. Los booleanos siempre son true y false en minúscula. No hay sorpresas porque el spec elimina deliberadamente todas las sorpresas.

TOML es la elección correcta para:

• Configs de tooling en los ecosistemas Rust y Python (Cargo.toml, pyproject.toml).
• Archivos con estructura mayoritariamente plana y algunas secciones.
• Cualquier cosa donde quieres una sensación tipo YAML sin las trampas de YAML.

TOML es la elección incorrecta para:

• Datos profundamente anidados (la sintaxis de secciones se vuelve verbosa rápido).
• Cualquier sitio donde el ecosistema se estandarizó en otra cosa (Kubernetes es YAML, las APIs REST son JSON, no pelees con la convención).

Cómo elegir en 30 segundos

Si el archivo lo lee o escribe código en ambos lados: JSON. Si el archivo vive en un contexto Kubernetes / CI / Ansible: YAML, no hay elección. Si el archivo es config de tooling en Python o Rust: TOML, el ecosistema lo espera. Si arrancas de cero con una config editada por humanos y tienes elección real: TOML por defecto, YAML si necesitas profundidad.

Convertir entre ellos

La mayoría de parsers pueden convertir cualquiera de estos a cualquier otro, con matices. JSON a YAML es sin pérdida. YAML a JSON pierde los comentarios. TOML a JSON es sin pérdida. JSON a TOML pierde limpio solo si el JSON es mayoritariamente plano.

Cuando recibas una config y quieras inspeccionarla, pégala en el formateador JSON de AldeaCode después de convertirla. El buscar y reemplazar es útil cuando estás migrando una config YAML a TOML y necesitas intercambiar patrones de sintaxis. Las dos corren en tu navegador, sin subida, sin log.

El resumen honesto: JSON para máquinas, YAML donde el ecosistema lo exige, TOML cuando tienes elección real y quieres que el formato se quite de en medio. Elegir el correcto desde el principio ahorra más tiempo que cualquier mejora de parser.