Conversor de JSON a YAML

Qué hace esta herramienta

Convierte un documento JSON en YAML y después te dice por qué cada cadena acabó entre comillas. Esa segunda parte es la razón de ser de la herramienta: cualquier otro conversor devuelve la salida y te deja descubrir más tarde que uno de tus valores ya no es una cadena.

La conversión va en un solo sentido. Leer YAML es un problema mucho mayor que escribirlo, y un analizador de YAML parcialmente correcto es peor que ninguno: acepta tu fichero y devuelve datos equivocados sin quejarse. Emitir es un problema acotado, y ese es el sentido que se cubre aquí.

Por qué un conversor necesita criterio

JSON dice de qué tipo es cada cosa. Una cadena lleva comillas, un número no, y no hay una tercera posibilidad. YAML, en cambio, decide el tipo de un valor sin comillas mirando su forma: si coincide con el patrón de un booleano es un booleano, si coincide con un número es un número, y solo si no coincide con nada se queda como texto.

Eso es lo que hace agradable escribir YAML a mano y lo que convierte la conversión en un juicio. Cada cadena de la entrada hay que contrastarla con cada patrón que YAML resuelve, y entrecomillarla si coincide con alguno. Equivócate hacia el lado seguro y la salida es ruidosa; equivócate hacia el otro y un valor cambia de tipo en silencio.

El problema de Noruega y sus parientes

El caso más conocido es una lista de códigos de país. Noruega es NO, y en YAML 1.1 el token sin comillas NO es el booleano false. Un fichero de configuración que enumera países pierde Noruega y gana un false, y nada en ninguna parte informa de un error.

No es una regla rara aislada, sino toda una familia. YAML 1.1 lee y, Y, yes, no, on y off como booleanos, en cualquier capitalización, lo que atrapa un símbolo químico, la posición de un interruptor y la respuesta a una pregunta. Y los resolvedores numéricos son aún más extraños:

• 12:30 es 750. YAML 1.1 lee los dígitos separados por dos puntos en base 60, así que una hora del día o una duración se vuelve un entero.
• 0755 es 493. Un cero inicial significa octal en YAML 1.1, y en YAML 1.2 ese mismo texto es el decimal 755: las dos versiones discrepan sobre qué número, no sobre si es número.
• 1.10 es 1.1. Un número de versión de dos partes es un float y el cero final desaparece. Una dependencia fijada en 1.10 ahora apunta a 1.1.
• 2024-01-30 es un objeto fecha, no una cadena, porque YAML 1.1 tiene un tipo de marca temporal.
• Una cadena vacía es null, igual que las palabras sueltas null, Null, NULL y la virgulilla.

Ninguno de estos es un fallo de YAML. Son los resolvedores haciendo exactamente lo que prometen, sobre un texto que da la casualidad de que coincide. La única defensa es entrecomillar todo lo que coincida, que es lo que hace esta herramienta y lo que el panel de hallazgos justifica línea a línea.

Dos versiones, y por qué la antigua es la predeterminada

YAML 1.2 llegó en 2009 y eliminó la mayoría de los resolvedores sorprendentes. Su esquema básico conserva solo true y false como booleanos, descarta la base 60 por completo y no tiene tipo de marca temporal. Bajo 1.2, NO y 12:30 y 2024-01-30 son simplemente cadenas.

La trampa está en qué lee realmente tu fichero. PyYAML implementa YAML 1.1, y PyYAML es el analizador que hay detrás de una cantidad enorme de herramientas: Ansible, clientes antiguos de Kubernetes, incontables guiones. yaml.v3 de Go y el js-yaml actual siguen 1.2. Así que el mismo documento puede leerse de dos maneras distintas según quién lo abra, y la única salida segura en todas partes es la entrecomillada para 1.1.

Ese es el valor por omisión aquí. Cambiar el ajuste a 1.2 no esconde nada: reemite con los resolvedores nuevos y el panel de hallazgos se encoge, así que ves con precisión qué comillas estaban ahí por el esquema antiguo. Las que quedan son las que necesita cualquier analizador.

Cadenas que rompen la sintaxis, no el tipo

Un segundo grupo de cadenas hay que entrecomillarlo por otro motivo: no porque YAML fuera a leerlas como otro tipo, sino porque no se analizarían como texto en absoluto.

• Dos puntos seguidos de un espacio terminan una clave. «note: time: now» se leería como una clave note cuyo valor es una clave time.
• Un espacio seguido de una almohadilla inicia un comentario, así que todo lo que venga después desaparece.
• Un -, ?, :, [, ], {, }, #, &, *, !, |, >, %, @ o acento grave inicial es un carácter indicador y significa algo estructural.
• Un espacio inicial o final no lo conserva un valor sin comillas, así que « x » vuelve como «x».
• Un tabulador en cualquier parte del valor se rechaza de plano: PyYAML rehúsa el documento entero en vez de leerlo mal, así que este falla en voz alta.

Se usan comillas simples siempre que basten, porque tienen exactamente una regla de escape —un apóstrofo se escribe dos veces— y se leen mejor que los escapes con barra que traen las comillas dobles. Las dobles quedan reservadas para lo que de verdad necesita escaparse: caracteres de control, tabuladores y cadenas de varias líneas que no pueden usar un bloque.

Cadenas de varias líneas y el indicador de recorte

Una cadena con saltos de línea —un guion, un certificado, un bloque de prosa— suele ser la razón por la que alguien quiere YAML en primer lugar. JSON solo puede escribirla con escapes de barra-n en una única línea larguísima; YAML tiene el escalar de bloque literal, que se abre con una barra vertical y donde el texto aparece sangrado y legible debajo.

La sutileza está en qué ocurre con los saltos de línea del final, y eso lo controla el indicador de recorte:

• Una barra vertical sola recorta: tenga el bloque los saltos finales que tenga, el valor se queda con exactamente uno.
• Una barra vertical seguida de un menos elimina: el valor no se queda con ninguno.
• Una barra vertical seguida de un más conserva: el valor se queda con todos.

Esta herramienta elige el indicador a partir de la cadena que recibió, de modo que el valor sobrevive al viaje de ida y vuelta exactamente. Conviene saberlo porque el valor por omisión —la barra sola— es el que la gente escribe a mano, y normaliza en silencio una cadena que terminaba en dos saltos de línea o en ninguno.

Un escalar de bloque no puede con todo, y donde no puede, la salida recurre a comillas dobles y el panel de hallazgos dice por qué. Un retorno de carro no sobrevive, porque los escalares de bloque normalizan los saltos de línea. Una primera línea que empieza con un espacio se leería como sangría adicional y se perdería. Y una línea que acaba en espacio la conserva la especificación, pero es invisible en pantalla y la mayoría de los editores la eliminan al guardar, así que entrecomillar es lo más seguro: eso es una decisión y no una limitación, y se informa como tal.

Más de un documento

YAML tiene algo que JSON no: un fichero puede contener un flujo de documentos separados por tres guiones. Ese es el formato de un manifiesto de Kubernetes, y es la razón por la que un array de JSON tan a menudo necesita convertirse en algo que no sea una secuencia YAML.

El interruptor de aquí emite cada elemento de un array de nivel superior como su propio documento. Y cuando la entrada no es un único valor JSON sino que cada línea se analiza por su cuenta, se lee como NDJSON —el formato delimitado por líneas en el que llegan los registros y las exportaciones de API— y cada línea pasa a ser un documento. Esa lectura es una conjetura, así que se informa encima de la salida en vez de hacerse en silencio.

El recurso solo se aplica cuando toda la entrada falla al analizarse y cada línea lo consigue, cosa que un documento simplemente mal formado no hará. Un error de sintaxis sigue apareciendo como un error de sintaxis, con la línea y la columna en que ocurrió.

Lo que la conversión no puede preservar

Dos cosas se pierden antes de que esta herramienta vea tus datos, ambas en el propio análisis de JSON, y conviene saber cuáles.

Claves duplicadas. JSON permite que un objeto liste la misma clave dos veces y la mayoría de los analizadores se quedan con la última en silencio. YAML prohíbe los duplicados de plano, así que la salida será válida, pero el valor anterior ya se ha perdido, y ningún conversor puede informar de lo que nunca recibió.

Precisión de enteros. Un número JSON mayor de unos nueve mil billones no sobrevive al análisis a un double, así que un identificador como 12345678901234567890 vuelve redondeado. No es un problema de YAML ni uno que introduzca esta herramienta; ocurre en todos los analizadores JSON del lenguaje. Si un identificador grande importa, va en una cadena por ambos lados.

Notas sobre la salida

La sangría es con espacios, siempre, porque YAML prohíbe los tabuladores para sangrar por completo: esa es una de las pocas cosas en las que el formato es estricto. Dos espacios es la convención; se ofrecen cuatro porque algunos estilos de casa los quieren.

Las secuencias van sangradas bajo su clave. Tanto eso como la forma sin sangrar son YAML válido y significan lo mismo; la sangrada es la que escribe la mayoría de la gente y la que la mayoría de los editores pliega bien.

Un array u objeto vacío se escribe en estilo de flujo como un par de corchetes o llaves, porque el estilo de bloque no tiene manera de expresar el vacío: no hay nada que escribir en las líneas siguientes.

La salida termina con un salto de línea, y eso es funcional y no cosmética. El recorte de un escalar de bloque se mide contra el salto de línea que le sigue, así que un bloque recortado al final del fichero sin salto final pierde el salto que debía conservar.