¿Qué es YAML? Sintaxis, tipos de datos, usos y trampas

La API de raspado sin residuos devuelve datos web estructurados en JSON o CSV, los cuales una tubería controlada puede transformar en YAML cuando se necesita un límite de configuración editado por humanos.

¿Qué significa YAML?

YAML significa “YAML no es un lenguaje de marcado”. Es un lenguaje de serialización de datos basado en Unicode diseñado para mapear limpiamente a estructuras de programación comunes. Un documento YAML se construye a partir de tres tipos de nodos principales: asignaciones para asociaciones clave-valor, secuencias para colecciones ordenadas y escalares para valores individuales.

El especificación de YAML 1.2.2 describe el modelo de representación, el árbol de serialización, el flujo de presentación, la sintaxis, las etiquetas y los esquemas. La capa de presentación de YAML ofrece varias formas de escribir datos equivalentes, lo que ayuda a los autores humanos pero da a los implementadores más opciones que la gramática más pequeña de JSON.

YAML es datos, no un lenguaje de instrucciones por definición. Las aplicaciones lo utilizan con frecuencia para configurar implementaciones, sistemas de construcción, trabajos de automatización, metadatos de sitios estáticos y herramientas locales para desarrolladores. La aplicación decide qué claves son válidas y qué hacen esas claves.

Sintaxis básica de YAML

Una configuración YAML puede combinar asignaciones, secuencias, números, booleanos y valores anidados:

service:
  name: catalog-worker
  enabled: true
  workers: 4
  regions:
    - us-east
    - eu-west
  output:
    format: json
    include_metadata: true

Dos puntos separan una clave de mapeo de su valor. Un guion introduce un elemento de secuencia en estilo bloque. La indentación coloca name, enabled, y la configuración restante bajo service. El documento no necesita llaves o comas en este estilo.

Asignaciones

Una asignación asocia claves con valores. Las claves son comúnmente cadenas simples, aunque el modelo de lenguaje permite claves más complejas. Los autores de configuración deben preferir claves de cadena simples y únicas porque las bibliotecas de aplicación y las herramientas de validación las manejan de manera predecible.

Las claves de mapeo duplicadas son un problema de portabilidad. Las bibliotecas pueden rechazarlas, mantener un valor, o exponer un comportamiento controlado por una opción. Un cargador de configuración de producción debería rechazar duplicados para que un revisor y la aplicación en ejecución vean la misma configuración efectiva.

Secuencias

Una secuencia es ordenada. El estilo bloque utiliza un guion por elemento, mientras que el estilo fluido utiliza corchetes:

regions: [us-east, eu-west]

checks:
  - name: schema
    required: true
  - name: links
    required: true

Cada elemento puede ser un escalar, un mapeo o otra secuencia. El orden solo debe usarse cuando el contrato de la aplicación le asigna significado.

Escalares y comillas

Los escalares incluyen cadenas, números, booleanos, nulos, marcas de tiempo bajo algunos esquemas y valores con etiquetas explícitas. Los escalares simples omiten comillas, pero la puntuación y ciertas palabras pueden interpretarse de maneras inesperadas a través de versiones de YAML o esquemas de analizadores. Cotiza valores cuando su forma textual debe permanecer exacta, incluidos números de versión, identificadores con ceros a la izquierda y cadenas que se asemejan a booleanos o nulos.

Las cadenas entre comillas simples tratan la mayoría de los caracteres de forma literal. Las cadenas entre comillas dobles admiten secuencias de escape. Los escalares en bloque utilizan | para preservar los saltos de línea o > para plegar líneas en espacios, con indicadores adicionales que controlan la indentación y los saltos de línea finales.

Comentarios, anclas, alias y etiquetas

Un carácter hash inicia un comentario fuera de un escalar entre comillas. Los comentarios hacen que YAML sea atractivo para la configuración porque los mantenedores pueden explicar por qué existe una configuración. Los comentarios son parte de la presentación en lugar del modelo de datos central, por lo que muchos analizadores los descartan al cargar y escribir un documento.

Una ancla etiqueta un nodo, y un alias se refiere a ese nodo en otro lugar. Esto puede reducir la configuración repetida:

defaults: &defaults
  timeout_seconds: 30
  output: json

jobs:
  catalog:
    <<: *defaults
    region: us-east

La clave de fusión que se muestra aquí se usa ampliamente, pero el comportamiento de fusión no es una característica universal simple de cada ruta de procesamiento de YAML. Confirme lo que la biblioteca y la aplicación elegidas admiten. Gráficas de anclaje excesivas también hacen que la revisión de la configuración sea más difícil porque el valor efectivo ya no es visible en un solo lugar.

Las etiquetas identifican el tipo o la interpretación de un nodo. Las etiquetas estándar cubren cadenas, enteros, asignaciones, secuencias y otros valores fundamentales. Algunas bibliotecas admiten etiquetas específicas de la aplicación que construyen objetos de lenguaje. Cargar etiquetas no confiables en constructores de objetos puede ser peligroso; utilice un cargador seguro que limite la construcción a los tipos de datos esperados.

Esquemas YAML y diferencias de versión

Un esquema YAML determina cómo el texto escalar se resuelve a etiquetas. Las diferencias de versión y esquema explican muchos ejemplos sorprendentes encontrados en los repositorios de configuración. Una palabra interpretada como un booleano por un modo de procesamiento puede seguir siendo una cadena bajo otro. La sintaxis numérica y el manejo de marcas de tiempo también pueden variar.

YAML 1.2 alineó su esquema JSON para que los documentos JSON sean YAML válidos en el modelo de compatibilidad previsto. Eso no significa que cada archivo YAML sea JSON válido: los comentarios, las claves no citadas, las colecciones en bloque, las anclas, los alias y las etiquetas son características de YAML fuera de la sintaxis de JSON.

El especificación del tipo de medio YAML registra application/yaml y el +yaml sufijo de sintaxis estructurada. Una extensión de archivo por sí sola no indica el esquema de analizador o el contrato de aplicación. Los proyectos deben fijar la biblioteca de analizador, documentar la versión o subconjunto de YAML admitido y validar los datos cargados contra un esquema de aplicación.

YAML vs JSON

Casos de uso comunes de YAML

Seguridad y Confiabilidad de YAML

YAML no confiable debe ser tratado como entrada estructurada no confiable. Use un modo de carga segura que construya solo valores de datos ordinarios, no objetos específicos de lenguaje o clases de aplicación. El riesgo general pertenece a la categoría más amplia descrita por CWE-502: Deserialización de Datos No Confiables.

Establezca límites en el tamaño de entrada, profundidad de anidamiento, alias y expansión agregada. Un documento pequeño puede referirse a valores anclados muchas veces, causando que un cargador cree una estructura en memoria mucho más grande. Las bibliotecas exponen diferentes controles, por lo que las pruebas deben ejercitar el analizador implementado con límites representativos.

Valide los datos cargados después de analizar. Rechace claves de nivel superior desconocidas cuando los errores de configuración serían peligrosos. Verifique campos requeridos, valores de enumeración permitidos, rangos numéricos, restricciones de ruta y relaciones entre configuraciones. No registre secretos ni toda la configuración en un error de validación.

Errores comunes de YAML

• Usar tabulaciones para la indentación. Preferir espacios y hacer cumplir un ancho de indentación a través de la configuración del editor y un formateador.
• Dejar escalares ambiguos sin comillas. Cotejar identificadores y texto que se asemeje a un booleano, nulo, número o marca de tiempo.
• Permitir claves duplicadas. Configura el cargador o linter para rechazarlas.
• Suponiendo que los comentarios sobrevivan a los viajes de ida y vuelta. Muchos cargadores basados en objetos descartan comentarios y formato original.
• Abusar de anclajes y combinaciones. El reutilizar puede reducir la repetición, pero los valores efectivos ocultos dificultan las revisiones y sobrescrituras.
• Saltar la validación del esquema. Un documento bien formado aún puede contener claves mal escritas o valores inseguros.

Cómo utilizar YAML correctamente

1. Define un pequeño subconjunto soportado. Decide si el proyecto permite anclajes, claves de combinación, etiquetas personalizadas, flujos de múltiples documentos y estilo de flujo.
2. Fija el analizador y el comportamiento. Registra la biblioteca, versión de YAML soportada, política de claves duplicadas y modo de carga segura.
3. Agrega linter y verificaciones de esquema. Ejecuta estas verificaciones antes del despliegue para que los errores de indentación y claves desconocidas fallen temprano.
4. Mantén los secretos fuera del YAML comprometido. Haz referencia a los valores proporcionados por el entorno o el gestor de secretos de acuerdo al mecanismo documentado de la aplicación.
5. Revisa la configuración efectiva. Cuando existe herencia o combinación, proporciona un comando que represente la configuración final sin exponer valores secretos.
6. Usa otro formato cuando cambie el límite. Prefiere JSON para APIs públicas y formatos analíticos tipados para grandes conjuntos de datos.

Conclusión

YAML es un lenguaje de serialización flexible cuyo estilo de bloque legible lo hace especialmente útil para la configuración. Su conveniencia viene con una superficie de interpretación más grande: la indentación, esquemas, etiquetas, anclajes, alias, claves duplicadas y opciones de analizador pueden afectar los valores cargados. Un flujo de trabajo YAML confiable reduce el conjunto de características soportadas, usa carga segura, valida los datos resultantes y mantiene la configuración amigable con los humanos separada del intercambio de máquina a gran volumen.