YAML vs JSON: cuál escribir y qué hace mal cada uno

Usa JSON cuando un programa escribe el archivo y otro programa lo lee: respuestas de API, registros almacenados, cualquier cosa que cruce una red. Usa YAML cuando lo escribe una persona que tendrá que volver a entenderlo seis meses después: pipelines de CI, manifiestos de Kubernetes, Docker Compose, configuración de aplicaciones. YAML te da comentarios, strings multilínea legibles y muchísima menos puntuación. Lo pagas con una indentación que significa algo, una especificación mucho más grande y un sistema de tipos que tarde o temprano convertirá el código de país NO en false. En realidad no compiten — desde YAML 1.2, todo documento JSON válido es también YAML válido — así que la pregunta de verdad es cuál escribes a mano.

Los mismos datos, de las dos maneras

En JSON:

{
  "name": "build",
  "retries": 3,
  "branches": ["main", "release/*"],
  "env": { "NODE_ENV": "production" }
}

En YAML:

# el build nocturno
name: build
retries: 3
branches: [main, "release/*"]
env:
  NODE_ENV: production

Los dos producen el mismo objeto. YAML elimina las llaves, las comillas de las claves y todas las comas, y agrega un comentario que JSON no tiene forma de expresar. Fíjate en la línea de branches: eso es sintaxis JSON, y sigue siendo legal dentro de un archivo YAML. Mezclar los dos estilos es normal, y para listas cortas suele ser lo más claro.

Lo que YAML tiene y JSON no

Comentarios. Este es el grande, y la razón por la que casi todos los formatos de configuración que empezaron como JSON se fueron desviando hacia otra cosa. Un archivo de configuración sin un lugar donde escribir "deja esto en 3, los valores más altos disparan el rate limiter" es un archivo de configuración que acumula decisiones que nadie sabe explicar. El diseñador de JSON quitó los comentarios a propósito, porque la gente había empezado a usarlos para transportar directivas de parseo.

Strings multilínea que se pueden leer. Un script de shell o un certificado PEM dentro de JSON se convierte en una sola línea larguísima llena de escapes \n. YAML tiene block scalars: | conserva los saltos de línea exactamente como están escritos, > pliega las líneas en un párrafo. Los dos quitan la indentación circundante, así que el texto no arrastra el layout de tu archivo hasta dentro del valor.

Varios documentos en un archivo. El separador --- permite que un archivo contenga una lista de objetos sin relación entre sí, que es la razón por la que un deployment, un service y un ingress de Kubernetes suelen viajar en un único archivo YAML. JSON no tiene equivalente; lo más parecido es JSON Lines, un objeto compacto por línea.

Reutilización. Los anchors y aliases (&defaults y *defaults) te dejan definir un bloque una vez y apuntar a él más adelante; las merge keys (<<) lo insertan dentro de otro mapping. Esta es también la primera funcionalidad que da problemas: la mayoría de las herramientas no logra devolver un alias tal cual, los parsers no se ponen de acuerdo sobre el orden del merge, y unos pocos aliases anidados pueden expandir un archivo diminuto en gigabytes de memoria — un truco de denegación de servicio lo bastante viejo como para tener apodo, la bomba YAML.

Lo que JSON tiene y YAML no

Una forma obvia de escribir cada cosa. Toda la gramática de JSON cabe en una sola página de diagramas de sintaxis. YAML tiene tres maneras de escribir un string — plano, entre comillas simples, entre comillas dobles —, dos estilos de block scalar con sus propios modificadores de salto final, flow style, block style y un capítulo entero de reglas sobre dónde puede ir el espacio en blanco. Esa flexibilidad es la razón por la que dos personas que editan el mismo archivo YAML producen diffs que no se ponen de acuerdo en el estilo.

Un parser en la biblioteca estándar. Python, JavaScript, Go y todos los demás leen JSON sin instalar nada. YAML casi siempre significa una dependencia, y cuál sea esa dependencia importa, porque los parsers difieren justo en los casos que muerden.

Espacio en blanco que no significa nada. Puedes minificar JSON, pegarlo en un campo de formulario, meterlo en una variable de shell o mandarlo por correo, y sobrevive. Pega YAML en cualquier cosa que lo reindente y habrás cambiado los datos. Por eso mismo JSON es lo que viaja por la red y YAML es lo que vive en un repositorio.

Sin tipado implícito. En JSON, lo que va entre comillas es un string y lo que no lleva comillas es un número, true, false o null. No hay nada que adivinar. YAML resuelve los escalares sin comillas por patrón, que es el origen de cada punto de la sección siguiente.

Dónde muerde YAML

El problema de Noruega

YAML 1.1 trataba yes, no, on y off como booleanos. Así que una lista de códigos de país que contenga un NO sin comillas llega como false, y la clave on: del principio de un workflow de GitHub Actions es, bajo esas reglas, el booleano true y no la palabra. YAML 1.2 redujo los booleanos a true y false nada más, pero muchos parsers todavía se comportan como en 1.1 — el loader por defecto de PyYAML entre ellos —, así que la respuesta depende de qué biblioteca lee tu archivo. Poner el valor entre comillas lo arregla bajo todas las versiones, y por eso los archivos de configuración cuidadosos ponen comillas casi en todo. El conversor de este sitio usa por defecto la regla de 1.2 y tiene un interruptor que vuelve a parsear el archivo con las reglas de 1.1. Activarlo es la forma más rápida de ver cuáles de tus valores sin comillas están a punto de cambiar de significado delante de un parser antiguo.

Números que cambian de forma

Escribe version: 1.0 y obtienes el float uno, que la mayoría de los emisores imprime de vuelta como 1 y que ya no coincide con el string "1.0". Escribe 1.2.3 y, al llevar un punto de más, se queda como string. Un ID de 17 dígitos o más pierde precisión en cuanto pasa por cualquier cosa construida sobre los números de JavaScript, porque el entero más grande que estos representan de forma exacta es 9.007.199.254.740.991. Bajo las reglas de 1.1, 12:30 era notación en base 60 y llegaba como el entero 750, que es como una lista de horas se convierte en una lista de cantidades de minutos. Pon entre comillas todo aquello cuyo texto exacto importe.

La indentación es la sintaxis

No hay llaves que te digan dónde termina un bloque, así que un valor en el margen equivocado no falla — se engancha a otro padre y el archivo carga igual. Los tabs no están solo desaconsejados como indentación; la especificación los prohíbe, y el error que obtienes rara vez lo dice. Dos espacios por nivel es la convención, y la consistencia dentro de un bloque importa más que el número que elijas.

Claves duplicadas

La especificación considera un error tener dos claves iguales en el mismo mapping. Muchos parsers se encogen de hombros y se quedan con la última, así que un ajuste agregado al final de un archivo largo puede sobrescribir en silencio esa misma clave 200 líneas más arriba. Cuando un cambio parece no tener ningún efecto, revisa esto primero.

Dónde muerde JSON

Sin comentarios. Tampoco hay coma final, lo que convierte una adición de una línea en un diff de dos líneas y es una causa común de que un archivo de configuración no cargue. Ni NaN ni Infinity. Y las claves duplicadas tampoco están prohibidas ahí: el RFC 8259 dice que los nombres de un objeto deberían ser únicos, pero no llega a exigirlo, y los parsers en general se quedan con el último.

El otro costo es la legibilidad a escala. Una configuración JSON de 400 líneas con todo entre comillas es difícil de recorrer, y una minificada es imposible — por eso volver a indentarla suele ser el primer paso para leer la respuesta de API de otra persona, una técnica que la guía para formatear JSON minificado cubre en condiciones.

Hay una trampa que pertenece a los dos formatos. Un secret en un manifiesto de Kubernetes parece revuelto porque está en base64, y base64 es una codificación, no cifrado — cualquiera que pueda leer el archivo puede leer el secreto.

Convertir de uno a otro

Tarde o temprano algo más abajo en la cadena solo acepta JSON — un validador de esquemas, el cuerpo de una solicitud HTTP, un filtro de línea de comandos — y lo que tienes es YAML. Como YAML es el superconjunto, esa dirección es casi mecánica, y un conversor que corre en el navegador la hace sin que el archivo salga de tu computadora — algo que importa aquí, porque los archivos de configuración son justo el tipo de cosa que todavía guarda un token que alguien olvidó quitar.

Lo que no sobrevive al viaje es todo lo que JSON no puede expresar. Los comentarios desaparecen. Los anchors y aliases hay que resolverlos en estructura duplicada, o rechazarlos — el conversor de aquí se detiene con un número de línea en vez de adivinar. De un archivo con varios documentos solo cruza el primero, y te avisa cuántos había. La dirección contraria no necesita conversor alguno: un JSON válido ya es YAML válido, así que puedes ponerlo en un archivo .yaml tal cual. Se leerá como JSON hasta que alguien lo reescriba en block style, pero no se pierde nada.

Entonces, ¿cuál?

• Un payload de API, una línea de log, una entrada de caché, un mensaje en una cola — JSON. Todos los runtimes ya lo hablan, y nada en él depende del espacio en blanco.
• La definición de un pipeline, un manifiesto de despliegue, la configuración de una app que alguien va a editar — YAML, aunque solo sea por los comentarios.
• Un archivo que escribe un programa y que una persona lee de vez en cuando — JSON, indentado con dos espacios. Generar YAML correcto es más difícil que generar JSON correcto.
• Cualquier cosa donde el error deba detectarse en la puerta — JSON con un esquema. YAML también se valida contra un JSON Schema, porque el modelo de datos es el mismo, pero estás confiando en que el parser te haya dado los valores que querías.

Última actualización 19 de septiembre de 2026