YAML vs JSON en DevOps: Guía práctica de formatos de configuración

Si has trabajado con infraestructura de software moderna, te has encontrado con YAML y JSON como formatos de configuración. Kubernetes usa YAML para sus manifiestos. GitHub Actions usa YAML para workflows. Docker Compose usa YAML. Ansible usa YAML. Mientras tanto, las APIs REST, APIs de configuración y estándares de intercambio de datos prefieren JSON casi universalmente. Entender cuándo y por qué usar cada formato no es un ejercicio teórico — afecta directamente la mantenibilidad de tu código de infraestructura y la velocidad con que tu equipo puede depurar incidentes en producción.

JSON (JavaScript Object Notation) fue diseñado como un formato ligero de intercambio de datos. Su sintaxis es mínima: llaves para objetos, corchetes para arrays, pares clave-valor con dos puntos, y cadenas siempre entre comillas. JSON es estricto por diseño — una coma faltante o extra causará un error de parseo. Esta estrictez hace a JSON ideal para comunicación máquina-a-máquina, donde la predictibilidad y el parseo determinista son primordiales. JSON.parse() en JavaScript es una única llamada nativa. El compromiso es la legibilidad: estructuras JSON profundamente anidadas pueden volverse visualmente densas, y JSON no soporta comentarios.

YAML (YAML Ain't Markup Language) fue diseñado con la legibilidad humana como objetivo principal. YAML usa sangría en lugar de corchetes para denotar anidamiento, lo que lo hace visualmente similar a un documento natural. YAML soporta comentarios (con prefijo #), permitiendo documentar por qué se eligió un valor de configuración directamente en el archivo. YAML también soporta tipos de datos más complejos incluyendo cadenas multilínea, anclas y alias (definir un valor una vez y referenciarlo múltiples veces), e inferencia de tipos. Estas características hacen a YAML mucho más expresivo para archivos de configuración, pero introducen su propia clase de peligros, particularmente alrededor de la sensibilidad a la sangría.

La fuente más común de errores en YAML es la sangría. A diferencia de JSON, YAML usa sangría para determinar la estructura. Un solo espacio mal colocado o una tabulación puede silenciosamente cambiar el significado de una configuración entera. Mezclar tabulaciones y espacios es un error frecuente. La mayoría de los parsers de YAML tratan las tabulaciones como espacio en blanco inválido, pero algunos no lo hacen, llevando a diferencias sutiles de comportamiento entre herramientas. En manifiestos de Kubernetes, una sangría faltante en un mapeo de puerto puede enrutar silenciosamente tráfico al contenedor incorrecto. Usar un linter o formateador automatizado ayuda a capturar estos problemas antes de que lleguen a producción.

Los manifiestos de Kubernetes son un ejemplo principal de dónde YAML brilla y dónde su complejidad puede volverse una liability. Un manifiesto de Deployment típico contiene API version, kind, metadata y un bloque spec con replicas, selector, template, containers, ports y variables de entorno. El anidamiento puede alcanzar fácilmente cinco o seis niveles de profundidad. Los ingenieros de DevOps frecuentemente luchan con errores de sangría al escribir estos manifiestos a mano. La mejor práctica es definir componentes reutilizables como Helm charts o Kustomize overlays, pero incluso entonces, entender la estructura YAML cruda es esencial para depuración. Convertir entre YAML y JSON puede ayudar: si una herramienta o SDK espera entrada JSON, puedes convertir tu configuración YAML sin reescribir tu fuente de verdad.

Los pipelines de CI/CD representan otro dominio donde YAML domina pero JSON a veces se requiere. GitHub Actions, GitLab CI, CircleCI y Azure Pipelines todos usan YAML para definiciones de pipeline. Estos archivos pueden crecer complejos rápidamente con builds matriciales, pasos condicionales, variables de entorno y referencias a secretos. Mientras el soporte de YAML para anclas y aliases ayuda a reducir duplicación, también significa que entender el orden completo de evaluación importa. Al depurar un pipeline fallido, convertir YAML a JSON puede revelar problemas ocultos como tipos incorrectos o coerción inesperada de tipos.

La coerción de tipos es uno de los comportamientos más sorprendentes de YAML para recién llegados. En YAML, las cadenas 'yes', 'true', 'on' y '1' pueden interpretarse como booleano true dependiendo del contexto. En la práctica, la mayoría de equipos de DevOps establecen YAML como su formato principal de configuración para archivos autoría humana y JSON para datos generados por máquina, respuestas de API y configuración programática. La capacidad de convertir entre los dos formatos rápidamente — sin copiar datos entre diferentes herramientas — es una capacidad de alto impacto. Ya sea migrando un deployment de Kubernetes, generando archivos de variables de Terraform, o depurando un workflow de GitHub Actions, poder pegar YAML e instantáneamente ver el JSON equivalente (o viceversa) remueve fricción del loop de depuración.