YAML a JSON: convierta manifiestos, redacte archivos y canalizaciones sin perder datos

Pasé una tarde el año pasado depurando un archivo de valores de Helm que un colega juró que era correcto. Todas las claves parecían correctas. El servicio se negó a iniciarse. El culpable resultaron ser cuatro personajes: NO como código de país, sin citar, en una lista de regiones. El analizador YAML lo leyó como booleano false, la plantilla renderizada false en un encabezado, y la solicitud fue rechazada aguas abajo con un mensaje de error que no mencionaba ni a YAML ni a Noruega. Ese error es lo suficientemente famoso como para tener un nombre (el problema de Noruega) y es sólo el de una familia de sorpresas esperando en un formato que la mayoría de nosotros tratamos como "JSON con espacios en blanco más agradables."

TL;Dr: los Convertidor YAML a JSON analiza un documento YAML e imprime el JSON equivalente, resolviendo anclajes, alias, claves de combinación y escalares de bloques a lo largo del camino. Al ver su configuración como JSON, le muestra exactamente lo que el analizador decidió que significan sus valores, qué tipos infirió, qué referencias expandió, antes de que esa interpretación llegue a un clúster. Se ejecuta completamente en su navegador.

Convertir YAML a JSON no es sólo un cambio de formato. Es la auditoría disponible más rápida de lo que realmente contiene su configuración. JSON no tiene comentarios, ni anclajes, ni escritura implícita más allá de lo que la sintaxis establece directamente, por lo que la vista JSON de un manifiesto es la versión resuelta e inequívoca del mismo. Esta guía cubre cómo YAML se asigna a JSON, el tipo y los comportamientos de referencia que causan incidentes reales, y cómo usar el convertidor cuando está depurando una configuración, comparando secuencias de comandos con un manifiesto o escribiendo un dispositivo de prueba.

¿qué hace realmente convertir YAML a JSON?

La relación se define, no incidental: la Especificación YAML 1.2 afirma que YAML es un superconjunto de JSON, por lo que cada documento JSON ya es YAML válido. YAML y JSON describen las mismas tres cosas: asignaciones de claves a valores, secuencias ordenadas y escalares. La conversión recorre el documento YAML y emite cada construcción en su equivalente JSON. Un mapeo de bloques se convierte en un objeto. Una secuencia de bloques se convierte en una matriz. Un escalar se convierte en una cadena, número, booleano o nulo, dependiendo de cómo lo resuelva el esquema central de YAML.

La parte estructural no es interesante porque es mecánica. Lo interesante es todo lo que YAML puede expresar que JSON no puede, porque ahí es donde el convertidor tiene que tomar una decisión en su nombre:

Característica YAML	Lo que obtiene JSON	Por qué importa
Comentarios (# ...)	Caído	JSON no tiene sintaxis de comentarios; La documentación en su configuración no sobrevive
Anclas y alias (&base, *base)	Copias ampliadas	JSON no tiene sintaxis de referencia, por lo que los bloques compartidos están duplicados
Fusionar claves (<<: *base)	Aplanado en el objeto	Las claves explícitas anulan las fusionadas, según la especificación de clave de fusión
Bloquear escalares (`	, &gt;`)	Una sola cuerda con escapes
Multiple documente (---)	Una variedad de documentos	Un paquete de Kubernetes se convierte en una matriz JSON, un elemento por recurso
Mecanografía implícita	Tipos resueltos	Sin comillas 8080 se convierte en un número, true un boolean, null un nulo

Esa última fila es la que vale la pena mirar. JSON obliga a cada valor a declarar su tipo mediante sintaxis: comillas cadena media, dígitos desnudos número medio. YAML infiere el tipo a partir de la forma del texto. La conversión a JSON hace visible la inferencia. Si esperabas una cadena de versión y JSON te lo muestra 1.1 donde dijo el YAML 1.10, ha encontrado un error que de otro modo habría enviado.

Por qué la escritura implícita de YAML's provoca cortes reales

El esquema central YAML 1.2 resuelve un escalar no citado por patrón. Los dígitos se convierten en números enteros. Los dígitos con un punto decimal o exponente se convierten en flotadores. true y false conviértete en booleanos. null y ~ volverse nulo. Todo lo demás es una cadena.

Eso suena ordenado hasta que cumples con los valores que parecen un tipo y están pensados como otro:

• Puertos e ID. port: 08080 no es el número 8080. Un cero inicial lo convierte en un número entero no válido según el esquema principal, por lo que la mayoría de los analizadores devuelven la cadena y algunos más antiguos la interpretan como octal. Los códigos postales, los números de teléfono y los ID de cuenta con ceros iniciales tienen el mismo problema.
• Versiones. version: 1.10 es la carroza 1.1. El cero final desapareció y ningún analizador te lo advierte. Compare eso con una etiqueta de contenedor y la búsqueda falla.
• Códigos de país e idioma. En YAML 1.1, que PyYAML sigue de forma predeterminada, junto con muchas herramientas Ruby y Java más antiguas, y, n, yes, no, ony off son booleanos. NO, ONy NA son códigos de dos letras perfectamente comunes en el mundo real.
• Tiempos y sexagesimales. YAML 1.1 también analiza 12:30 como número de base 60, que es 750. Las cadenas tipo Cron o duración pueden desaparecer en números enteros.

Cada uno de estos es una corrupción de datos silenciosa, no un error de análisis. El documento es válido, la canalización es verde y el valor es incorrecto. El convertidor's Mantenga las cuerdas existe una opción para exactamente esta clase de investigación: enciéndalo y cada escalar simple regresa como una cadena, para que pueda comparar las dos conversiones una al lado de la otra y ver con precisión qué valores estaba reinterpretando el analizador. Lo que sea que muestre el JSON sin esa opción es lo que probablemente esté haciendo su analizador de producción hoy.

La solución en su YAML fuente es siempre la misma: cite cualquier cosa cuyo significado sea textual. port: "8080", version: "1.10", region: "NO". Las cotizaciones no cuestan nada y eliminan toda la categoría de error. Si genera YAML desde JSON en lugar de escribirlo, el Convertidor JSON a YAML aplica esa cita automáticamente para valores ambiguos.

Cómo se convierten los anclajes, los alias y las claves de fusión

Los anclajes son YAML's respuesta a la repetición. Marcas un nodo con &name, luego haz referencia a él más tarde con *name:

defaults: &defaults
  restartPolicy: Always
  terminationGracePeriodSeconds: 30

web:
  <<: *defaults
  replicas: 3

worker:
  <<: *defaults
  terminationGracePeriodSeconds: 120

JSON no tiene forma de decir " el mismo valor que allí." Entonces el convertidor expande cada referencia a una copia completa. La salida anterior se convierte en tres objetos, cada uno con el suyo propio restartPolicy, y el JSON es más largo que el YAML que lo produjo. Eso no es un defecto en la conversión: es lo que significa YAML, escrito.

La clave de fusión << merece su propia nota porque su regla de precedencia es fácil de retroceder. Las claves escritas explícitamente en el mapeo secundario ganan sobre las claves extraídas por la fusión. En el ejemplo, worker termina con un período de gracia de 120, no de 30, independientemente de si la línea de fusión aparece encima o debajo de la clave explícita. El convertidor implementa esa regla, por lo que JSON le muestra la configuración efectiva posterior a la fusión, que suele ser lo que realmente quería inspeccionar.

De esto se derivan dos usos prácticos. Primero, cuando una configuración utiliza un anclaje pesado, convertir a JSON es la forma más rápida de responder " ¿A qué se resuelve realmente este entorno?" sin ejecutar la implementación. En segundo lugar, si un alias no tiene un ancla coincidente (un resultado común de dividir un archivo grande en varios), el convertidor lo informa como un error con el número de línea, en lugar de producir un nulo silenciosamente.

Cómo se convierten los escalares de bloques

YAML tiene dos formas de incrustar texto multilínea y se comportan de manera diferente:

• Literal (|) mantiene cada salto de línea exactamente como está escrito. Úselo para scripts de shell, certificados PEM, SQL y cualquier cosa sensible a espacios en blanco.
• Doblado (>) une líneas consecutivas con un solo espacio y trata una línea en blanco como una ruptura de párrafo. Úselo para la prosa que desea incluir en el archivo fuente pero que se une al valor.

Ambos aceptan un indicador de masticación que controla las nuevas líneas finales. El valor predeterminado, llamado recorte, mantiene exactamente una nueva línea final. Un menos (|-) elimina todas las nuevas líneas finales. Un plus (|+) se queda con cada uno de ellos.

En JSON, todo esto colapsa en una sola cadena \n escapa. Ésa es otra razón por la que la vista JSON es útil: es inequívoca. Un | bloque cuya última línea fue sangrada accidentalmente, o a > bloquear esas dos líneas plegadas que pretendía mantener separadas es obvio en JSON y casi invisible en YAML. El convertidor también maneja el caso que detecta implementaciones ingenuas: a # el carácter dentro de un bloque literal es contenido, no un comentario, lo cual importa en el momento en que incrustas un script de shell que comienza con un shebang.

Cómo utilizar el convertidor YAML a JSON

Paso 1: Pegue el documento

Pegue cualquier YAML en el panel de entrada: un manifiesto de Kubernetes, a docker-compose.yml, un flujo de trabajo de GitHub Actions, un manual de Ansible, a .gitlab-ci.yml, o una configuración de aplicación. Archivos multidocumentos con --- los separadores están bien: cada documento se analiza de forma independiente. Haga clic Cargar muestra para comenzar desde una implementación realista que ejercita mapas anidados, secuencias, una colección vacía y un escalar de bloques literal.

Lo único que no analizará es la sangría con caracteres de pestaña. YAML prohíbe las pestañas directamente y el convertidor lo dice con el número de línea infractora en lugar de adivinar. Los editores que insertan una pestaña en Enter son la fuente habitual; la mayoría tiene un " convertir sangría en espacios" comando que corrige todo el archivo a la vez.

Paso 2: elige la forma de salida

Elegir 2 espacios, 4 espacios, o Minificado. Minified es lo que desea cuando está a punto de pegar el resultado en a curl variable de cuerpo o entorno. La salida sangrada es lo que desea cuando un humano tiene que leerla.

Ordenar claves reescribe las teclas de objeto alfabéticamente en todos los niveles. Esto es invaluable al comparar dos versiones de una configuración: dos archivos que difieren solo en el orden de las teclas producen JSON ordenado idéntico, por lo que una diferencia solo muestra cambios reales. Introduzca ambas salidas en el Diferencia de JSON herramienta y obtienes una comparación estructural precisa en lugar de una línea por línea.

Mantenga las cuerdas desactiva la coerción escalar, como se describe anteriormente. Úselo cuando desee ver el texto sin procesar de cada valor, o cuando un consumidor posterior trate todo como una cadena de todos modos.

Paso 3: Convierte y lee los errores

clic convertido. Si el documento está bien formado, el JSON aparece a continuación junto con el recuento de líneas, el recuento de claves, el tamaño de bytes y, para flujos de múltiples documentos, cuántos documentos se encontraron.

Si no está bien formado, el error nombra la línea. Los mensajes cubren las fallas que realmente ocurren en la práctica: pestañas utilizadas para sangría, una línea sangrada de manera inconsistente con sus hermanos, una cadena entre comillas sin terminar, un alias sin ancla, una clave de combinación que apunta a algo que no es un mapeo. Un número de línea convierte una búsqueda de cinco minutos en una solución de cinco segundos.

Paso 4: Copie, descargue o continúe

Copie el JSON a su portapapeles o descárguelo como .json archivo. A partir de ahí, los siguientes pasos comunes son imprimir y validar bastante con Formateador JSON, generando tipos para un cargador de configuración con JSON a mecanografiado, o derivar un contrato para la validación de CI con el Generador de esquemas JSON.

Flujos de trabajo reales que se ajustan a esto

Depurar un manifiesto que "se ve bien"

Cuando una implementación se comporta inesperadamente y el YAML lee correctamente, conviértala. Nueve de cada diez veces el JSON muestra el problema inmediatamente: un valor que se volvió booleano, una clave anidada un nivel menos profundo de lo previsto debido a un espacio perdido, un ancla que se expandió a algo obsoleto. La vista JSON elimina la ambigüedad de los espacios en blanco que hizo invisible el error.

Scripting contra configuración

Los scripts Shell y Node manejan JSON de forma nativa; YAML necesita una dependencia. Cuando necesito extraer cada etiqueta de imagen de un paquete de manifiestos, primero convertir a JSON y canalizarlo jq es más rápido que agregar una biblioteca YAML a un script desechable. El soporte multidocumento de Converter's importa aquí: un paquete de seis recursos de Kubernetes se convierte en una matriz JSON que puede iterar.

Accesorios de prueba de construcción

Las pruebas de integración a menudo necesitan un objeto de configuración en lugar de un archivo de configuración. Convertir el manifiesto real a JSON le brinda un dispositivo que garantiza que coincide con la forma de producción, que es un punto de partida mucho mejor que un objeto que escribió desde la memoria. Emparejarlo con JSON a mecanografiado y tu accesorio viene con tipos.

Revisar la configuración en una solicitud de extracción

Las diferencias de YAML fuertemente anclado son difíciles de leer porque un cambio de una línea a un ancla cambia silenciosamente a cada consumidor. Convirtiendo ambas versiones con Ordenar claves habilitado y diferenciando, el JSON muestra el radio de explosión real: cada valor resuelto que cambió, no solo la línea que se editó.

Migrando entre herramientas

Muchas plataformas aceptan JSON pero no YAML, o viceversa. La conversión suele ser toda la migración. Cuando necesitas volver al revés, JSON en la mano, YAML requiere, el Convertidor JSON a YAML cierra el bucle y el Validador YAM confirma los análisis de resultados antes de confirmarlo.

Comparación de YAML y JSON

Dimensión	hablar con tachuelas	JISON
comentarios	sí	prohibido
Edición humana	Basado en sangría, fácil de rozar	Puntuación pesada, detallada
Análisis de máquinas	Analizadores más lentos y grandes, más casos de borde	Analizadores pequeños y rápidos por todas partes
Tipo de inferencia	Implícito, dependiente del esquema	Explícito de la sintaxis
referencias	Anclas, alias, claves de fusión	nadie
Múltiples documentos por archivo	Sí, vía ---	prohibido
Hogar típico	Archivos de configuración, canalizaciones de CI, manifiestos	API, intercambio de datos, almacenamiento

YAML 1.2 es formalmente un superconjunto de JSON, por lo que cada documento JSON ya es YAML válido. Lo contrario no es cierto, por lo que convertir YAML a JSON es una operación con pérdida exactamente en una dirección: los comentarios y la estructura de referencia se descartan, mientras que los datos se conservan. Si su YAML tiene comentarios que le interesan, mantenga el YAML como fuente de verdad y trate el JSON como un artefacto derivado.

Privacidad: por qué esto se ejecuta en su navegador

Los archivos de configuración se encuentran entre los artefactos de texto sin formato más confidenciales que tiene un equipo. Llevan nombres de host internos, nombres de clúster, rutas de registro, cuentas de servicio, identificadores de bases de datos y, a pesar de las mejores intenciones de todos, la credencial ocasional que aún no se ha convertido en un administrador secreto.

El convertidor es JavaScript del lado del cliente. Su documento se analiza en la página, el JSON se produce en la página y ninguna solicitud transporta sus datos a ninguna parte. Cargue la herramienta una vez y seguirá funcionando con la red apagada, lo cual es un hábito razonable para cualquier cosa en la que pegue un manifiesto. Este es el mismo principio detrás de cada herramienta del sitio, y el razonamiento se detalla en la guía Privacidad de datos en herramientas en línea. Si está reuniendo un conjunto de herramientas de navegador de uso general, el Kit de herramientas para desarrolladores web la guía cubre lo que hay en ella.

Limitaciones que vale la pena conocer

Ningún convertidor que encaje en la pestaña del navegador implementa cada esquina de la especificación YAML, y es más útil ser específico sobre los bordes que dar a entender que no los hay.

Claves de mapeo complejas: las explícitas ? key los formularios donde la clave es en sí misma una secuencia o mapeo no son compatibles, porque las claves de objeto JSON deben ser cadenas. Escriba etiquetas como !!binary o personalizado !MyType las directivas no se interpretan; el valor aparece como texto. Los valores flotantes especiales .inf, -.infy .nan se conservan como cadenas, ya que JSON no tiene un literal para ellas y se convierte silenciosamente a null perdería más información de la que ahorra. Directivas como %YAML 1.2 se ignoran en lugar de actuar en consecuencia.

Ninguno de estos aparece en archivos Kubernetes, Compose, Actions o Ansible ordinarios. Si presiona uno, está trabajando con un documento escrito para un idioma específico 's biblioteca YAML, y esa biblioteca 's propio dumper es la herramienta correcta.

preguntasrán el

¿Cómo convierto YAML a JSON en línea?

Pegue su YAML en el panel de entrada y haga clic en Convertir. El analizador lee el documento, resuelve los anclajes y los escalares de bloques e imprime JSON con formato que puede copiar o descargar. Todo sucede en su navegador, por lo que no se carga ningún archivo.

¿JSON es un subconjunto de YAML?

Sí. YAML 1.2 se redefinió como un superconjunto estricto de JSON, por lo que cualquier documento JSON válido también es válido YAML. Lo contrario no es cierto: YAML agrega comentarios, anclas, escalares de bloques, múltiples documentos por archivo y claves que no son de cadena, ninguna de las cuales JSON puede expresar directamente.

¿Cómo se convierten los anclajes y alias YAML a JSON?

JSON no tiene sintaxis de referencia, por lo que cada alias se expande a una copia completa del valor que define su ancla. Una configuración que reutiliza un bloque predeterminado tres veces produce tres objetos JSON idénticos. Por lo tanto, la salida es mayor que la fuente YAML pero semánticamente idéntica.

¿qué sucede con las teclas de fusión como el soporte de doble ángulo?

La asignación a la que se hace referencia se fusiona con el objeto actual. Claves escritas explícitamente en la cartografía de menores ganan sobre las claves combinadas, que coinciden con el comportamiento de la especificación de clave de combinación de YAML y de Kubernetes y las herramientas de Ansible.

¿por qué mi YAML falló con un error de pestañas?

YAML prohíbe la sangría de caracteres de pestañas: la especificación solo permite espacios. Los editores que insertan pestañas en Enter son la causa habitual. Convierta las pestañas principales en espacios, lo que la mayoría de los editores pueden hacer con un archivo completo a la vez, y el documento se analizará.

¿puedo convertir un archivo YAML multidocumento con separadores de documentos?

Sí. Cada documento entre los marcadores separadores se analiza de forma independiente y el resultado es una matriz JSON con un elemento por documento, en orden de origen. Un archivo de un solo documento devuelve el objeto en sí, no una matriz de un solo elemento.

¿Los números de puerto y las cadenas de versión mantendrán su tipo?

Los escalares simples se resuelven mediante el esquema central YAML, por lo que un 8080 sin comillas se convierte en el número 8080 y un 1,10 sin comillas se convierte en 1,1. Cite el valor en su YAML para mantenerlo como una cadena, o active la opción Mantener cadenas para desactivar toda coerción escalar.

¿cómo se convierten los escalares de bloques literales y plegados?

Un bloque literal mantiene cada nueva línea, por lo que se convierte en una cadena JSON con saltos de línea escapados. Un bloque plegado une líneas consecutivas con un espacio y trata las líneas en blanco como saltos de párrafo. Se respetan los indicadores de masticación: un menos elimina la nueva línea final y un más mantiene cada línea final en blanco.

---