Convertir JSON a YAML

Esta es de las pocas conversiones de este sitio en las que la respuesta a «qué me va a costar» es literalmente nada. Desde la versión 1.2, publicada en 2009, la especificación de YAML define JSON como un subconjunto suyo: todo documento JSON válido ya es un documento YAML válido. La conversión vuelve a escribir el mismo árbol con otro estilo.

Eso hace que el resto de esta página sea rara. No hay un paso con pérdida del que avisar, ni aplanamiento, ni un tipo que haya que aproximar. Lo que hay son preguntas sobre cómo va a leerse el resultado, y resultan importar más de lo que importaría una pérdida de datos.

El escritor sigue YAML 1.2, donde no, yes, on y off son cadenas corrientes. Así que un valor JSON de «no» se escribe como un no desnudo, sin comillas, y volver a leer ese documento con un analizador 1.2 devuelve la misma cadena. Ese comportamiento es correcto y viaja de ida y vuelta sin un rasguño.

YAML 1.1 no opina lo mismo: resuelve esas palabras a valores booleanos, y PyYAML —lo que usan Ansible, media herramienta escrita en Python y una cantidad enorme de scripts internos— es un lector 1.1. El problema es que la lista de palabras afectadas está en inglés, y el castellano tropieza justo con una: «no». Un campo de respuesta, una columna de consentimiento, un formulario donde alguien contestó no; entra como cadena y sale como falso. Curiosamente «sí» está a salvo, porque no figura en esa lista. Si aguas abajo hay algo escrito en Python, entrecomilla esos valores a mano después de convertir.

El mismo mecanismo alcanza a los identificadores cortos. NO es el código ISO de Noruega y ON el de Ontario, y ambos aparecen sin comillas en un YAML escrito bajo la regla 1.2. Un catálogo de países, un listado de provincias o un fichero de tarifas por región puede convertirse de forma impecable y luego perder exactamente dos filas al ser leído por la herramienta equivocada.

Lo desagradable es que no falla: produce un valor válido de otro tipo. Nadie recibe un error, la validación pasa, y el país desaparece del informe sin que quede rastro de cuándo. Buscar en el fichero convertido las apariciones de no, yes, on y off sin comillas cuesta un minuto y es la única defensa que existe, porque ningún analizador va a avisar.

El entrecomillado se decide valor a valor y solo donde la forma desnuda se leería como otra cosa. La cadena «1.0» va entrecomillada, porque sin comillas es un número. «null» va entrecomillada, porque sin comillas es el valor nulo. Una cadena que empieza por almohadilla va entrecomillada, porque una almohadilla suelta abre un comentario, y una cadena con espacios al principio o al final también, porque YAML se los quitaría.

La regla es coherente y es una regla de la versión 1.2, que es justo el asunto de las dos secciones anteriores. Todo lo que el escritor entrecomilla cambiaría de significado bajo 1.2; las palabras que deja desnudas son las que solo cambian bajo 1.1. Una cadena con forma de fecha, 2024-01-01, se queda sin comillas por el mismo motivo, y un lector 1.1 la convierte en una marca de tiempo.

Una cadena JSON no puede contener un salto de línea literal, así que un script de arranque, un certificado o una sentencia SQL metidos en un manifiesto JSON son una única línea enorme con barras invertidas donde deberían estar los saltos. Revisar un cambio ahí dentro no es realmente posible.

El escritor de YAML emite esos valores como bloques literales: una barra vertical y a continuación el texto en sus propias líneas indentadas, con los saltos donde corresponde. Un script de doce líneas ocupa doce líneas del archivo. Para quien convierte porque el manifiesto tiene que pasar por los ojos de una persona, esta suele ser la mayor mejora del resultado, y es invisible hasta que el archivo contiene uno.

Un array JSON de objetos se convierte en la lista con guion delante que aparece en cualquier ejemplo de Kubernetes o de GitHub Actions: un guion, la primera clave en la misma línea y el resto indentado debajo. Contenedores, pasos, volúmenes, trabajos: todos llegan con la forma que enseña la documentación.

Eso importa para la revisión más que para la corrección, y la revisión es para lo que sirve el archivo. Quien repasa seis pasos de despliegue en YAML distingue dónde acaba uno y empieza el siguiente sin contar llaves, que es exactamente el motivo por el que este ecosistema eligió el formato pese a sus trampas de indentación.

JSON no admite comentarios, y no por descuido de los analizadores: la gramática no contempla ninguno, de modo que un analizador conforme no tiene nada que aceptar. YAML los admite en cualquier punto donde una línea pueda empezar por almohadilla. Convertir un manifiesto generado a YAML muy a menudo no va de sintaxis: va de convertir el archivo en un sitio donde el motivo de un valor pueda vivir junto al valor.

La salida no lleva ningún comentario, porque la entrada no tenía ninguno que traer. Añadirlos es la primera edición que merece la pena, y los útiles nunca describen qué es un campo. Escribe por qué el número de réplicas es tres, con qué otro repositorio tiene que coincidir la etiqueta de la imagen y qué se rompe si alguien baja el tiempo de espera.

YAML tiene anclas y alias, que permiten definir un bloque una vez y referenciarlo en tres sitios, y admite varios documentos en un mismo archivo separados por tres guiones. Ambas cosas se usan mucho —los ficheros de compose y los paquetes de manifiestos viven de ellas— y ninguna puede salir de un origen JSON, porque JSON no sabe expresar ni una ni otra.

El archivo convertido queda entonces correcto y plano: todo lo que se repetía en el JSON se repite en el YAML. Factorizar esa repetición con un ancla es una edición manual, y solo merece la pena donde la repetición sea real. El otro caso es un conjunto de manifiestos separados concatenados en un array JSON; ahí el resultado correcto son varios documentos en un archivo, que otra vez es una edición y no una conversión.

La conversión conserva el orden en que llegaron las claves, así que apiVersion, kind y metadata siguen donde estaban en lugar de acabar alfabetizadas. Ni JSON ni YAML definen el orden de un mapa como significativo y hay herramientas que lo reordenan alegremente, pero un manifiesto con las claves ordenadas por alfabeto se lee peor y produce un diff enorme sin motivo.

Vale la pena saberlo al comparar la salida con un archivo que ya esté en el repositorio. Si los dos solo se diferencian en el orden, la diferencia viene de lo que produjo el JSON y no de esta conversión: leer un recurso desde un clúster, por ejemplo, devuelve los campos en el orden del servidor de la API y no en el que tú los escribiste.

La comprobación más barata es la de la propia herramienta: aplicar en seco con kubectl, pedirle a compose que muestre la configuración resuelta, o pasar el analizador de flujos de trabajo. Cada una interpreta el documento y describe la forma que ha encontrado, lo que detecta una clave mal colocada mucho más rápido que leer el archivo.

La comprobación que caza el problema del entrecomillado es otra y hay que hacerla a conciencia, porque ningún validador la hará por ti: busca en el archivo convertido los no, yes, on y off sueltos y cualquier fecha sin comillas, y decide para cada uno si algún lector 1.1 va a verlo alguna vez. Es un minuto de trabajo y es la única parte de esta conversión que no avisa sola.

La conversión ocurre en esta pestaña. El JSON lo interpreta el analizador del propio navegador y el YAML lo escribe una biblioteca que se carga bajo demanda, así que ninguna petición transporta el documento a ningún sitio, no hay registro ni cupo diario y el plan gratuito acepta hasta 100 MB por archivo, muchísimo más de lo que ocupa cualquier manifiesto.

Para este lector eso es una cuestión práctica y no abstracta. Un manifiesto sacado de un clúster en funcionamiento contiene nombres internos, rutas de registro, cuentas de servicio y la forma de la infraestructura, y en bastantes organizaciones pegar eso en un conversor público es un incidente que hay que notificar. Aquí no hay nada que pegar ni nada que enviar.