YAML vs JSON: cuándo usar cada uno

Abres dos archivos de configuración que contienen exactamente los mismos ajustes. Uno está envuelto en llaves y comillas; el otro se lee casi como un esquema. Llevan datos idénticos y, sin embargo, no se parecen en nada. Esa distancia, estricto frente a legible, es toda la historia de YAML contra JSON, y te dice cuál usar y cuándo.

En resumen: JSON y YAML describen las mismas formas: mapas, listas y valores simples. JSON es estricto, de llaves y corchetes, e ideal para las API y los datos de máquina a máquina donde importa un análisis garantizado. YAML se basa en la sangría, admite comentarios y es mucho más amable de editar a mano, por eso los archivos de configuración lo prefieren. Cualquier YAML se convierte a JSON y de vuelta. Elige JSON para el intercambio de datos y YAML para la configuración que escriben las personas.

Qué tienen en común

Los dos formatos representan los mismos tres bloques de construcción: mapeos (pares de clave y valor), secuencias (listas ordenadas) y escalares (valores simples como texto, números y booleanos). Anida eso y puedes describir casi cualquier dato estructurado. Como el modelo de fondo coincide, los dos son intercambiables en contenido. Un documento en uno siempre se puede reescribir en el otro.

YAML, de hecho, formaliza este solapamiento. La especificación de YAML define el formato como un superconjunto de JSON, lo que significa que un archivo JSON válido ya es YAML válido. Puedes pegar JSON directamente en un analizador de YAML y funciona. Lo contrario necesita un paso de conversión, ya que YAML tiene funciones de las que JSON carece, pero no se pierde información en ninguna dirección. Por eso un conversor de YAML a JSON puede ir y volver con tus datos sin problemas: las formas son las mismas, solo cambia la sintaxis de la superficie.

Así que cuando la gente pregunta qué formato es más capaz, la respuesta honesta es que para los datos corrientes empatan. Las diferencias viven en la ergonomía, no en lo que puedes expresar.

Dónde gana JSON

JSON gana en cualquier sitio donde una máquina lee los datos. Su gramática es minúscula y rígida: llaves para los objetos, corchetes para los arreglos, comillas dobles en cada clave y cadena, comas entre los elementos y nada más. Esa rigidez es una ventaja. Un analizador casi no tiene ambigüedad que resolver, así que JSON se analiza rápido, se comporta igual en todos los lenguajes y rara vez te sorprende.

Esa fiabilidad es la razón de que las API se decantaran por él. Cuando un servidor envía datos a un navegador o un servicio llama a otro, ambos lados necesitan ponerse de acuerdo sobre el significado al instante, sin una persona de por medio que detecte un fallo. JSON cumple con eso. Casi todos los lenguajes de programación traen soporte para JSON en su biblioteca estándar, y todos los clientes HTTP lo entienden sin configuración extra.

El coste es la comodidad. JSON prohíbe los comentarios, así que no puedes anotar un archivo de configuración en línea. También rechaza las comas finales, esa coma inofensiva después del último elemento de una lista, que hace tropezar a la gente sin parar durante las ediciones a mano. Y cada cadena necesita comillas, cada clave necesita comillas, cada nivel necesita sus llaves cerradas. Para una máquina eso es trivial. Para una persona que lo teclea a mano, es una molestia.

Dónde gana YAML

YAML gana en cualquier sitio donde una persona escribe y lee el archivo. Quita la mayor parte de la puntuación: la estructura viene de la sangría en lugar de llaves y corchetes, las claves normalmente se saltan las comillas y separas los elementos con saltos de línea en vez de comas. El resultado se lee más como una nota estructurada que como código, y por eso domina en la configuración.

La función estrella son los comentarios. YAML te deja empezar una línea con una almohadilla y explicar un ajuste justo al lado, algo que el JSON estándar no puede hacer. Para un archivo que un compañero editará el mes que viene, ese comentario continuo vale mucho. YAML también admite anclas, una forma de definir un valor una vez y reutilizarlo, lo que recorta la repetición en configuraciones largas.

Esto es justo lo que hace que tanta herramienta de configuración recurra a YAML: las definiciones de canalizaciones de CI, los manifiestos de orquestación de contenedores e innumerables archivos de ajustes de aplicaciones se apoyan en él. Quienes mantienen esos archivos son personas, editando a mano, que se benefician de los comentarios y de una disposición que pueden recorrer con la vista. El intercambio es que YAML pide más cuidado al teclear, algo que cubre la siguiente sección.

Los tropiezos con los espacios en YAML

La flexibilidad de YAML viene con bordes afilados, y la mayoría se remontan a dos fuentes: los espacios en blanco y un exceso de celo al adivinar tipos. Como la estructura depende de la sangría, los espacios al inicio de una línea tienen significado. Si los pones mal, el archivo o no se analiza o, peor, se analiza con una forma distinta de la que pretendías mientras parece estar bien.

La mayor regla sobre los espacios: nunca sangres con tabulaciones. La especificación de YAML prohíbe los caracteres de tabulación para la sangría, así que una tabulación perdida que en tu editor se ve idéntica a los espacios puede romper el documento entero. Solo espacios, de forma consistente, en cada nivel.

Luego está la adivinación de tipos, que produce el famoso problema de Noruega. YAML intenta inferir los tipos a partir de los valores sin comillas, así que lee yes, true y on como booleanos. El código de país de Noruega, NO, se analiza como el booleano false en lugar del texto que querías. Los números con ceros a la izquierda, las cadenas de versión y las fechas pueden cambiar bajo tus pies de la misma forma. La defensa es un solo hábito: pon entre comillas cualquier escalar que necesites que se quede como cadena literal. Las comillas cuestan dos caracteres y borran toda una categoría de errores.

JSON esquiva todo esto. Su rigidez hace que los espacios en blanco sean decoración, nunca estructura, y toda cadena lleva comillas por definición, así que nada se reinterpreta en silencio.

Cómo elegir

La regla cabe en una frase: usa JSON para el intercambio de datos y YAML para la configuración que escriben las personas. Si una máquina produce o consume los datos, sobre todo a través de una red, recurre a JSON y consigue su velocidad, su soporte universal y su ambigüedad cero. Si una persona escribe y mantiene el archivo, recurre a YAML y consigue los comentarios además de una disposición legible.

La mayoría de los equipos acaban usando ambos, y eso es correcto y no indeciso. Tu API habla JSON porque las máquinas necesitan un contrato estricto. Tus ajustes de despliegue y de canalización viven en YAML porque las personas los ajustan a mano. Los dos no son tanto rivales como herramientas para lectores distintos.

Y cuando necesitas moverte entre ellos, la conversión es mecánica. Mete una configuración de YAML en un conversor de YAML a JSON para alimentar una herramienta que solo acepta JSON, o imprime con formato un bloque denso de JSON como YAML para leerlo con más facilidad. Como comparten un mismo modelo de datos, el viaje de ida y vuelta no pierde nada. El formato que tienes nunca tiene que ser el formato con el que te quedas atascado.