Entre el package.json, el docker-compose.yml y el Cargo.toml vives rodeado de tres formatos de serialización que resuelven lo mismo con filosofías opuestas. Elegir mal no rompe nada... hasta que sí: un Noruega que YAML convierte en booleano o una clave duplicada silenciosamente aceptada. Esta comparativa te da el criterio para decidir —y las trampas exactas de cada formato.
JSON: el mínimo denominador común
Diseñado como subconjunto literal de JavaScript (aunque hoy es independiente), su virtud es la previsibilidad absoluta:
{
"servidor": {
"puerto": 3000,
"hosts": ["api.midominio.es"],
"tls": true
}
}
- Tipado estricto: strings, números, booleans, null, arrays, objetos. Nada más.
- Claves duplicadas: la especificación dice "los nombres DEBEN ser únicos" pero no define comportamiento ante duplicados — cada parser decide. Trampa real.
- Sin comentarios: la ausencia más criticada. Las soluciones creativas (
"//": "nota") son hacks, no features. - Comas obligatorias entre elementos y prohibida la final — fuente eterna de errores de sintaxis a mano.
Donde brilla: intercambio de datos entre sistemas, APIs, configuración leída por máquinas. Donde duele: ficheros escritos y leídos por humanos.
YAML: máximo confort humano, máxima superficie de sorpresa
YAML usa indentación significativa y permite escribir casi sin comillas ni llaves:
servidor:
puerto: 3000
hosts:
- api.midominio.es
tls: true
Legible y compacto, sí. Pero su resolución de tipos implícita es legendaria:
pais: NO # ← booleano false (código de país de Noruega)
version: 1.30 # ← número, pierde el cero final si fuera 1.10
activo: yes # ← true en YAML 1.1, string en 1.2
dni: 08765432X # error de parseo en algunos parsers
octal: 0777 # ← 511 en YAML 1.1 (interpretación octal)
La lista completa de gotchas incluye: el Norway problem, claves duplicadas aceptadas silenciosamente por muchos parsers (la última gana, o la primera, según implementación), valores nulos escritos sin querer (clave: vacía = null), y el riesgo de seguridad histórico: algunos parsers permitían instanciar objetos arbitrarios al deserializar (el vector del ataque a Python años atrás). Reglas defensivas: siempre entrecomillar strings que empiecen por dígitos o letras ambiguas, usar parsers YAML 1.2 safe, y validar en CI.
Además, la indentación significativa convierte el copy-paste en deporte de riesgo: un espacio de más reestructura todo el árbol.
TOML: explícito y sin sorpresas
Creado precisamente porque "YAML es complicadísimo y JSON sin comentarios es insoportable", TOML apuesta por explicitud total:
[servidor]
puerto = 3000
tls = true
[servidor.tls_config]
cert = "/etc/letsencrypt/live/midominio/fullchain.pem"
[[hosts]]
nombre = "api.midominio.es"
- Tipado explícito: fechas nativas ISO, arrays tipados, tablas
[seccion]y arrays de tablas[[item]]. - Comentarios con
#de primera clase. - Claves duplicadas = error de parseo. Sin ambigüedad.
- Sin indentación significativa: reformatear no cambia nada.
Su punto débil: documentos profundamente anidados se vuelven verbosos y la sintaxis de arrays de tablas confunde al principio. Es el estándar de facto en Rust (Cargo), Python moderno (pyproject.toml) y Go (muchas herramientas).
Tabla de decisión
| Criterio | JSON | YAML | TOML |
|---|---|---|---|
| Legibilidad humana | Media | Alta | Alta |
| Seguridad de tipos | Estricta | Implícita traicionera | Estricta |
| Comentarios | No | Sí | Sí |
| Anidamiento profundo | Soportable | Natural | Verboso |
| Riesgo de parseo | Bajo | Alto | Mínimo |
| Dominio típico | APIs, datos | Kubernetes, CI/CD, Ansible | Cargo, pyproject, herramientas dev |
Reglas prácticas destiladas:
- Datos que viajan entre programas: JSON siempre.
- Configuración DevOps (k8s manifests, workflows): YAML por ecosistema, con validador en CI.
- Configuración de proyecto (build tools, dependencias): TOML donde el ecosistema lo ofrezca.
- Nada de YAML generado por concatenación de strings: genera estructuras y serializa; inyectar texto en YAML es cómo nacen los bugs de seguridad.
Valida antes de commitear
Un linter de formato evita el 90% de estos problemas. Para JSON, nuestro formateador y validador de JSON detecta sintaxis rota, muestra el árbol y formatea al vuelo; para conversiones desde CSV u otros orígenes hacia JSON, el convertidor CSV a JSON evita escribirlas a mano. Y si tu día a día es Docker Compose, la guía del stack con Compose muestra YAML real funcionando.
Preguntas frecuentes
¿Puedo poner comentarios en JSON? No en JSON estándar. Si tu herramienta lo tolera (VS Code settings usa JSONC), es extensión propia, no interoperable. Necesitas comentarios → usa TOML o YAML.
¿Y XML? Vivo en nichos (SOAP legacy, Android, Office docs) pero para configuración moderna ha perdido frente a los tres anteriores: verboso, namespaces complejos y parsing pesado.
¿HJSON o JSON5? Extensiones de JSON con comentarios y sintaxis relajada. Útiles internamente, peligrosas como interfaz pública: nadie más las soporta de serie.
Formatea y valida tu JSON con nuestro JSON Formatter online, gratis y directamente en tu navegador.