Formateador YAML

YAML es sensible a los espacios en blanco, lo que lo hace agradable de leer e implacable de editar. La herramienta de arriba hace tres cosas: deja tu YAML en una forma canónica, lo convierte a JSON y vuelve a convertir JSON en YAML. Todo ocurre en tu navegador, así que un manifiesto de Kubernetes o un fichero de CI con secretos nunca sale de tu máquina.

Cómo funciona

Elige un modo, pega tu documento y escoge una sangría de 2 o 4 espacios.

• Formatear YAML analiza el documento y lo vuelve a serializar. Así se normalizan la sangría, las comillas y el estilo de las listas, y las distintas formas de escribir un mismo valor quedan reducidas a una sola.
• YAML → JSON analiza el YAML y genera JSON con la sangría que elijas. Resulta útil para pasar un fichero de configuración a algo que solo entiende JSON, y para ver exactamente qué cree un parser que significa tu YAML.
• JSON → YAML hace lo contrario, y es la forma más rápida de convertir un bloque de JSON generado en algo que se pueda revisar en una pull request.

El análisis usa un parser de YAML 1.2 que cumple la especificación, así que los errores llegan como mensajes reales del parser, con línea y columna, en lugar de un genérico «entrada no válida». Ese texto de error suele ser lo más útil que produce la herramienta.

Ten en cuenta que formatear es un viaje de ida y vuelta por el modelo de datos, no una transformación del texto. Eso tiene una consecuencia que conviene saber desde el principio: los comentarios se pierden. Si los comentarios de tu fichero importan (y en un fichero de Kubernetes o de CI casi siempre importan), usa el modo de formateo para comprobar la estructura y luego aplica las correcciones a mano en el original.

Las trampas de YAML

La sangría tiene que ser con espacios. Los tabuladores están prohibidos en la sangría de YAML, sin excepciones. Un editor configurado para insertar tabuladores produce un fichero que no se puede analizar, con un error que señala el sitio equivocado.

El problema de Noruega. YAML 1.1 trataba yes, no, on, off, y y n como booleanos, de modo que una lista de países que contenía NO se interpretaba como false. YAML 1.2 eliminó ese comportamiento, pero muchos parsers en uso todavía implementan el de la 1.1. Pon entre comillas los escalares ambiguos: "NO", "on", "1.0".

Números de versión sin comillas. 1.0 es un float, 1.10 es el float 1.1 y 1.0.0 es una cadena. Los tags de imagen y las versiones fijadas deben ir siempre entre comillas.

Ceros a la izquierda. En parsers antiguos, 08 puede interpretarse como un octal no válido; "08" es seguro. Lo mismo vale para cualquier cosa que parezca un número pero sea un identificador: números de teléfono, códigos postales, referencias de cuenta.

Claves duplicadas. La especificación dice que no son válidas, pero muchos parsers se quedan con la última sin avisar. En un fichero largo, una clave repetida es un defecto que ningún mensaje de error te va a señalar.

Pasar un fichero por YAML → JSON resuelve todas estas dudas de golpe, porque JSON no tiene ambigüedad: lo que aparezca como true o 1.1 en la salida JSON es exactamente lo que vio tu parser.

¿YAML o JSON?

Ambos expresan el mismo modelo de datos, así que la elección depende de quién los va a leer. YAML es para ficheros que escriben y revisan personas: sus comentarios, sus escalares de bloque y sus anclas existen para eso. JSON es para máquinas: sin comentarios, sin ambigüedad, una sola forma de escribir cada valor y un parser en todos los lenguajes. Todo documento JSON es YAML 1.2 válido, y por eso la conversión de esta herramienta no pierde nada en ese sentido y en el otro solo conserva la estructura.

Dónde aparece

YAML es el lenguaje de configuración del mundo de los contenedores y la CI, y la mayoría de las veces que te lo encuentras estás depurando un problema de sangría en el fichero de otra persona. Redes y volúmenes en Docker Compose recorre la estructura de un fichero Compose, Fundamentos de Kubernetes cubre los manifiestos y el modelo de apply, y Pipelines de Jenkins y el Jenkinsfile trata la definición de pipelines. En el lado de la aplicación, Starters, propiedades y perfiles explica cómo se resuelve y se sobrescribe application.yml.

Para JSON por sí solo, el formateador de JSON es la herramienta más directa; para marcado, el formateador de HTML.