¿Qué es un archivo YAML?

YAML es un formato de texto plano que se abre en cualquier editor. Se usa para mover datos entre programas y la edición.

La extensión es .yaml y el nombre completo, YAML Ain't Markup Language. Ambos importan menos que lo que el archivo puede contener, y de eso trata el resto de esta página.

Se remonta a 2001. La especificación es YAML 1.2.

La edad interesa por un motivo práctico: cuanto más antiguo es un formato, más programas han tenido tiempo de aprenderlo.

Está publicada entera, así que cualquiera puede implementarla leyendo el documento en vez de a base de inspeccionar archivos. Por eso aparece en tantos programas, y por eso los archivos escritos hace veinte años siguen abriéndose hoy. Publicada no quiere decir libre de regalías: cuando un formato envuelve un códec, la licencia de las patentes es un asunto aparte que la norma no resuelve.

YAML guarda su contenido exactamente. Volver a guardarlo no cambia nada, así que puedes abrirlo, editarlo y guardarlo tantas veces como quieras sin acumular daño; eso es lo que lo convierte en un formato de trabajo y no de entrega.

YAML tiene sintaxis de comentarios, que es la diferencia entre un archivo que mantiene una persona y uno que escribe un programa. Los comentarios son lo primero que se pierde al convertir a un formato que no los tiene, y nada te avisa.

Visual Studio Code y yq lo leen, y también la mayoría de programas del mismo tipo.

Cuando un archivo no se abre, el formato rara vez es el problema: lo más habitual es que el programa sea anterior al formato. Convertir a algo más antiguo es la salida fiable, y para eso está el resto de este sitio.

Ningún navegador lo lee.

Ese es el motivo más frecuente para convertirlo: no que el formato sea malo, sino que el sitio donde quieres mostrar el archivo no sabe leerlo.

YAML está pensado para abrirse y cambiarse. Guarda el archivo en este formato mientras el trabajo siga en marcha y exporta desde él cada vez que haga falta una copia terminada.

Muy poca gente escoge este formato. Se lo entregan: manifiestos de Kubernetes, tuberías de GitHub Actions y de GitLab CI, playbooks de Ansible, Docker Compose, especificaciones OpenAPI, la cabecera de los generadores de sitios estáticos. Todos ellos se asentaron aquí, y los ecosistemas que los rodean son lo bastante grandes como para que la decisión ya no esté sobre la mesa.

Eso condiciona qué es una página útil sobre YAML. La pregunta casi nunca es si usarlo, sino cómo esquivar las formas concretas en que se tuerce, porque falla en silencio con más frecuencia que cualquier otro formato de configuración de uso corriente.

No hay llaves ni marcas de cierre. La profundidad a la que está escrita una línea determina de qué depende, así que un espacio de más cambia el significado del documento — y con bastante frecuencia produce un documento que sigue siendo válido y que dice otra cosa.

Dos reglas evitan casi todo. Nunca tabuladores: la especificación los prohíbe para sangrar, y un editor que meta uno provoca un error cuyo mensaje rara vez menciona la causa. Y sangrado constante, dos espacios por nivel por convención, porque mezclar anchos dentro de un mismo archivo es legal y deja la estructura ilegible de un vistazo.

YAML deduce qué es un valor escrito sin comillas, y sus deducciones han provocado caídas reales. La famosa es el problema de Noruega: en YAML 1.1 un no sin comillas es el booleano falso, de modo que en una lista de códigos de país el de Noruega deja de ser NO y pasa a ser false. Lo mismo ocurre con on, off, y y n.

Los números de versión son la segunda trampa: 1.20 se lee como el decimal 1,2 y el cero final desaparece. Las horas son la tercera, porque 22:30 puede interpretarse como un número sexagesimal en vez de como texto. Y un valor como 0755 puede leerse en octal.

La defensa no es saberlo, es una costumbre: entrecomilla todo lo que quiera decir texto. Versiones, códigos de país, identificadores, horas, cualquier cosa con ceros a la izquierda. YAML 1.2 arregló varios de estos casos y muchos analizadores siguen implementando el 1.1, así que lo que te protege es el hábito y no la especificación.

YAML permite definir un bloque una vez y reutilizarlo. Un ancla lo marca, un alias lo referencia, y una clave de fusión inserta un bloque común en varios sitios — que es como una tubería de integración continua evita repetir las mismas seis líneas en cada tarea.

Es genuinamente útil y es el punto donde YAML deja de ser legible para quien no ha visto la sintaxis antes. Dos advertencias prácticas: un alias es una referencia y no una copia, de modo que lo compartido está compartido; y varias herramientas que consumen YAML no implementan anclas o las expanden de maneras sorprendentes. Conviene comprobarlo antes de construir una configuración grande encima.

Un bloque escrito con una barra vertical conserva los saltos de línea: es lo correcto para un script, un certificado o un mensaje con párrafos. Escrito con el signo de mayor que, las líneas se pliegan en una sola, que es lo correcto para una frase larga partida por comodidad dentro del archivo.

Cada uno admite un sufijo que controla el salto final — un menos lo quita, un más conserva todos los que haya. Importa mucho más de lo que parece cuando el valor es una clave, un token o un script: un salto de línea sobrante es la explicación clásica de que un certificado se rechace o de que un comando se comporte distinto en la tubería que en tu máquina.

Tres guiones en una línea propia empiezan un documento nuevo, así que un solo archivo puede contener una secuencia de ellos. Kubernetes lo usa constantemente — un despliegue, un servicio y un mapa de configuración en el mismo archivo — y cualquier herramienta que lo lea lo espera.

Vale la pena saberlo porque cambia lo que significa «analizar este archivo». Un lector que carga un documento ignora en silencio todo lo que venga después del primer separador, que es como se pierde media configuración sin un solo error. La función correcta suele llamarse cargar todos los documentos, no cargar el documento.

Hacia JSON, XML, TOML y NDJSON el árbol se mantiene tal cual, con las claves en el orden en que estaban: nada en este conversor las ordena. Hacia INI no hay árbol posible, porque un INI es una lista plana de secciones y claves: la estructura anidada se aplana en claves con el camino separado por puntos — el primer nivel se convierte en el nombre de la sección y lo que cuelga de ahí en la clave dentro de ella — con los índices de los arrays convertidos en tramos de ese mismo camino.

Lo que no sobrevive a ninguna de esas salidas son los comentarios. Ni YAML, ni TOML, ni INI, ni XML los conservan aquí: el analizador produce un valor y no hay ningún canal donde guardar el texto que los acompañaba. Convertir un manifiesto documentado a JSON y volver deja el manifiesto sin una sola explicación, que es la clase de pérdida que nadie nota hasta que vuelve al archivo seis meses después. La conversión ocurre en tu navegador, con un tope de 100 MB por archivo.

Usa un editor con modo YAML. Te enseñará las guías de sangría, convertirá los tabuladores y marcará un error estructural donde está, en vez de dejar que lo encuentre un despliegue. Para cualquier cosa que vaya a un repositorio, un analizador en el gancho de confirmación vale los diez minutos que cuesta configurarlo.

Y valida antes de publicar cuando exista un esquema. Kubernetes, OpenAPI y la mayoría de sistemas de integración continua publican el suyo, y una validación atrapa la clave mal colocada que el analizador acepta encantado y el sistema rechaza a las tres de la madrugada.