La conversión es en realidad una pregunta sobre las reglas de tipos de YAML
El JSON es un subconjunto de YAML, lo que hace que una de las dos direcciones suene trivial y esconde dónde está el trabajo de verdad. Los dos formatos describen las mismas seis clases de valor, así que no se pierde nada estructural al ir de YAML a JSON. Lo que cambia es cómo decide cada formato qué significa un escalar sin comillas, y YAML tiene muchas más opiniones al respecto que JSON.
El null es el ejemplo fácil. El JSON lo escribe de una única manera. YAML acepta null, Null,
NULL, ~ y un valor vacío después de los dos puntos, y las cinco formas llegan a JSON como el mismo
null. Los números también van más sueltos: YAML lee 0x1F como 31 y 1e3 como un float, mientras
que el JSON no tiene literales hexadecimales en absoluto. Las marcas de tiempo son las que sorprenden,
porque un 2024-01-15 a secas es un tipo YAML de verdad, se convierte en un objeto de fecha real
durante el análisis, y después se serializa en JSON como la cadena ISO completa
2024-01-15T00:00:00.000Z, porque el JSON no tiene dónde meter una fecha.
Por eso “convertir mi YAML” no es una sustitución de texto. Ver cuáles de tus valores consideró número el analizador, cuáles cadena y cuáles booleano suele ser el motivo entero para pasar un manifiesto por aquí.
La trampa del yes y el no, y de qué lado está esta herramienta
Hay un patrón de error muy conocido según el cual un archivo de configuración con códigos de país
convierte NO en false, porque YAML 1.1 trataba yes, no, on y off como formas de escribir
booleanos. Picó a suficientes proyectos como para ganarse un apodo, el problema de Noruega.
Este conversor ejecuta js-yaml v4 con su esquema por defecto, que resuelve los booleanos a la manera
de YAML 1.2, así que los únicos booleanos son true y false. Ese esquema por defecto son los tipos
básicos de 1.2 más un puñado de extras que js-yaml conserva, y por eso funcionan las marcas de tiempo
y las claves de fusión de más abajo. Tu no sale como la cadena "no". Lo comprobamos contra la
biblioteca en lugar de fiarnos de la fama de YAML en general, porque cambia el consejo: si estás
depurando una configuración que malinterpretó una cadena de herramientas de Ruby, Perl o de un Python
antiguo, el resultado de aquí va a discrepar con la herramienta que se rompió, y esa discrepancia es
el hallazgo.
Esto tiene un matiz que le importa especialmente a quien escribe configuraciones en español. La
lista de booleanos de YAML 1.1 es de palabras inglesas, así que el trato era asimétrico: un archivo
que usara si y no como valores veía su no convertido en false mientras que su si se quedaba
como cadena, porque si no estaba en esa lista y no sí. Bajo el esquema 1.2 que usa esta
herramienta los dos se quedan como cadenas, que es el comportamiento coherente. Si de todas formas
querías booleanos, escríbelos como true y false.
Archivos con varios documentos y la decisión de usar loadAll
Las convenciones de Kubernetes meten varios recursos en un mismo archivo, separados por una línea
---. Casi todos los conversores ingenuos leen el primer documento y o bien se detienen o bien fallan,
porque el load normal de js-yaml rechaza de plano un flujo que contenga más de un documento.
Esta herramienta llama a loadAll en su lugar, y después toma una decisión de criterio sobre la forma
de la salida. Un archivo de un solo documento te devuelve el objeto o el array en sí, no un array de
un elemento envolviéndolo, porque es lo que espera quien pega una configuración corriente. Dos o más
documentos devuelven un array JSON con un elemento por documento, en el orden del origen. Así que un
archivo que agrupe un Deployment, un Service y un ConfigMap se convierte en un array de tres objetos
que puedes indexar. Una entrada genuinamente vacía, incluido un documento vacío entre dos separadores,
se convierte en null, que es lo que dice la especificación de YAML que contiene un documento vacío.
Lo que no sobrevive al viaje
Los comentarios son la gran pérdida y ninguna herramienta puede evitarlo. Un comentario con # no
forma parte del modelo de datos de YAML, así que el analizador lo descarta al leer; no queda ningún
comentario para cuando se escribe la salida, y el JSON tampoco tiene sintaxis para recibirlo. Cualquier
configuración donde los comentarios lleven el conocimiento acumulado debería editarse en su sitio, no
pasarse de ida y vuelta.
Otras dos cosas menores también se aplanan. Los anclajes y los alias se resuelven a sus valores, así
que un bloque &defaults referenciado tres veces, o incorporado con una clave de fusión, aparece tres
veces entero en el JSON en lugar de seguir siendo una referencia. Y las claves de mapeo que parecen
enteros se reordenan: los objetos de JavaScript enumeran las claves con aspecto de entero en orden
numérico ascendente sin importar el orden en que se escribieron, así que un mapeo con las claves 10
y 2 va a salir con el 2 primero. Entrecomilla esas claves en el origen si su orden importa.
En la dirección contraria
Cambia Dirección a JSON → YAML y la misma caja acepta JSON. La opción de sangrado (de 1 a 8 espacios, 2 por defecto) hace un trabajo útil en los dos modos: fija la sangría de la salida JSON en una dirección y la sangría de bloque de js-yaml en la otra. Los valores fuera de ese rango se acotan en lugar de rechazarse. En cualquiera de los dos casos son cuatro pasos:
- Pega tu YAML (o tu JSON) en la caja de texto de arriba.
- Deja Dirección en YAML → JSON, o cámbiala a JSON → YAML.
- Ajusta el tamaño de sangrado si el valor por defecto de 2 no es tu estilo de casa.
- Pulsa el botón y después Copiar al portapapeles. Un fallo de análisis aparece en la misma caja de salida, nombrando la línea y la columna, y no como un cartel de error genérico.
Esta es la dirección a usar cuando una herramienta exige YAML y lo que tienes es la respuesta de una API o una configuración exportada. Eso sí, no esperes que el resultado parezca escrito a mano. Un serializador toma decisiones consistentes sobre entrecomillado y estilo de flujo que no tomaría una persona, así que el YAML es correcto pero soso.
Leer un error de análisis
Las dos direcciones informan de los fallos como una única línea que nombra la posición y el motivo del propio analizador, en lugar de un cartel genérico de entrada no válida. El lado de YAML convierte la marca de base cero de js-yaml en la línea y la columna de base uno que muestra tu editor; el lado de JSON reutiliza la descripción de error ya escrita y probada para el formateador de JSON en vez de duplicar esa lógica.
Merece la pena dejar constancia de un detalle de la construcción. La función de conversión no lanza nunca una excepción, y es deliberado. El shell compartido de herramientas de texto captura cualquier error lanzado y sustituye su mensaje por un cartel fijo de que algo ha ido mal, lo que se habría tragado justamente lo único que esta herramienta existe para enseñarte. Así que el texto del error se devuelve como resultado y aterriza en la caja de salida, donde se puede leer.
Si tu entrada resulta ser XML en vez de YAML, el conversor de XML a JSON cubre esa forma, y el comparador de textos es el paso siguiente habitual una vez tienes dos configuraciones en el mismo formato y quieres ver qué cambia de verdad.
