JSON vs YAML vs TOML, Explicado

Ultima revision 2026-04-27. Abre el parser JSON o JSON to CSV para trabajo JSON en el navegador.

Los tres formatos lado a lado

La misma configuracion, tres formas:

JSON                        YAML                  TOML
{                           server:               [server]
  "server": {                 host: "localhost"   host = "localhost"
    "host": "localhost",      port: 8080          port = 8080
    "port": 8080
  }
}                                                 

JSON - estricto e inequivoco

El objetivo de diseno de JSON era un formato que cualquier lenguaje pudiera parsear identicamente. La gramatica es pequena (seis tipos de datos, reglas de espacio en blanco bien definidas). Cada parser produce el mismo arbol. Esa uniformidad es por lo que JSON domina las APIs, los archivos de configuracion para herramientas que vienen con un parser JSON, y la serializacion maquina-a-maquina.

Donde JSON es incomodo: los comentarios no estan permitidos, las comas finales son errores de sintaxis, y la configuracion anidada profundamente se vuelve ilegible para humanos. La solucion es JSON5 (JSON con comentarios y comas finales) para configuracion editada por humanos, mientras se mantiene JSON puro para transporte.

YAML - legible, a veces demasiado astuto

YAML se lee como notas de esquema. La indentacion crea estructura; las listas usan guiones; los valores no necesitan comillas. Los campos son cortos y el archivo es denso. Por eso YAML domina Kubernetes, GitHub Actions, Docker Compose, y configuraciones de CI - todos lugares donde los humanos editan el archivo diariamente.

Donde YAML duele: el espacio en blanco es significativo y los tabs rompen el parser. La cadena "yes" se parsea como el booleano true. El codigo de pais Noruega "NO" se parsea como false. Los numeros con ceros a la izquierda se parsean como octales. Las cadenas multilinea tienen cuatro sintaxis diferentes. El formato es legible por humanos pero no seguro para humanos; los bugs de parsing sutiles son comunes en produccion. La solucion es linter cada archivo YAML en CI y entrecomillar cualquier cadena que parezca que podria ser mal interpretada.

TOML - simple, poco profundo

TOML apunta al nicho de archivos de configuracion donde YAML es demasiado suelto y JSON es demasiado verboso. Secciones en corchetes, pares clave-valor con signos de igual, tipos nativos de fecha y hora. Cargo (gestor de paquetes de Rust), pyproject.toml en Python moderno, y varias herramientas de configuracion lo usan.

Donde TOML es incomodo: datos profundamente anidados. La sintaxis para arrays de tablas es verbosa y no es visualmente obvia. Para anidar mas de 2-3 niveles, YAML o JSON se leen mejor. TOML gana cuando la configuracion es naturalmente plana - una lista de dependencias, una lista de ajustes de compilacion, un pequeno conjunto de secciones nombradas.

Regla de decision

Maquina-a-maquina: JSON. Configuracion humana editada diariamente, con estructura principalmente plana: TOML. Configuracion humana editada diariamente, con estructura profundamente anidada: YAML, con linting en CI. En caso de duda, JSON - el rigor es seguro barato.

Para convertir entre formatos, ve JSON to CSV o el parser JSON. Para otras herramientas de desarrollo, el hub de herramientas de desarrollo.