Plain unquoted string — most common
name: John Doe
Single-quoted: no variable or escape processing
path: '/usr/bin/node'
Double-quoted: supports escape sequences (\n, \t, etc.)
message: "Hello\nWorld"
Whole number (base 10)
port: 8080
Floating point number
threshold: 0.95
Boolean value — use only true/false (YAML 1.2)
debug: false
Null / absence of value
response: null
ISO 8601 date format
created: 2024-01-15T10:30:00Z
Single-line comment. No multi-line comment syntax.
# This is a comment key: value # inline comment
Force value to be treated as a specific type
port: !!str 8080 # string '8080' not int
Key-value pairs — indented block style
app: name: myapp port: 3000
Inline map — equivalent to block style
env: {NODE_ENV: prod, PORT: 8080}List of items — block style with dash+space
fruits: - apple - banana - cherry
Inline list — equivalent to block style
ports: [80, 443, 8080]
List where each item is a map
users:
- name: Alice
role: admin
- name: Bob
role: userArbitrarily deep nesting
database:
primary:
host: db1.example.com
port: 5432Merge the keys of a referenced mapping into current map
defaults: &defaults color: blue button: <<: *defaults text: Submit
Preserves newlines exactly as written
script: | #!/bin/bash echo "hello" exit 0
Newlines folded into spaces (great for long descriptions)
description: > This is a very long description that will be joined into one line.
Literal block, strip all trailing newlines
prompt: |- Enter value:
Literal block, keep all trailing newlines
template: |+ line1
Folded block, strip trailing newlines
message: >- This folds into one line no trailing newline
Assigns an anchor (label) to the current node
base: &base image: node:18 restart: always
References (copies) an anchored node
service1: <<: *base name: api service2: <<: *base name: worker
Anchor a scalar value to reuse it
read_timeout: &rto 30 write_timeout: *rto connect_timeout: *rto
Anchor a list
primary_colors: &colors - red - blue text_colors: *colors
Explicitly declare YAML version (optional, rarely needed)
%YAML 1.2 --- name: myapp
Marks the start of a YAML document. Required if using directives.
--- kind: Deployment --- kind: Service
Marks the end of a YAML document. Optional but useful.
--- debug: true ...
Multiple YAML docs in one file (stream)
Used in Kubernetes multi-resource files
Base64-encoded binary data
icon: !!binary | iVBORw0KGgo=
Indentation MUST use spaces only — never tabs
# WRONG: parent: \tchild: value # RIGHT: parent: child: value
Values containing ': ' (colon+space) must be quoted
# WRONG: url: http://example.com # RIGHT: url: "http://example.com"
1.0 parses as float! Quote or tag it to keep as string
version: '1.0' # string version: 1.0 # float
YAML 1.1 parses yes/no/on/off as booleans — quote to use strings
# YAML 1.1 (PyYAML): on: true # 'on' is boolean true! # Safe: always quote on: 'on'
Trailing spaces in keys are included in the key string
"key " (with space) != "key" — trim carefully
Duplicate keys — behavior is parser-specific (usually last wins). Treat as error.
Use a YAML linter to detect duplicate keys
| Característica | YAML | JSON |
|---|---|---|
| Comentarios | Yes: # comment | No soportado |
| Comillas requeridas | Opcional para cadenas | Requerido para cadenas |
| Anchors/aliases | Yes: &anchor / *alias | No soportado |
| Cadenas multilínea | Yes: | and > blocks | Escaped \n only |
| Tabulaciones para sangría | Solo espacios | Ambos |
| Es superconjunto de JSON | Todo JSON es YAML válido | - |
| Legibilidad humana | Muy alta | Media |
| Disponibilidad de analizadores | Alta | Muy alta |
Importante: Muchos parsers YAML todavía usan YAML 1.1 por defecto (PyYAML de Python, Psych de Ruby en algunas versiones).
YAML tiene dos estilos multilínea:
Bloque literal (|) — preserva saltos de línea:
description: |
Esta es la línea uno.
Esta es la línea dos.
Esta es la línea cuatro (después de línea en blanco).
Bloque plegado (>) — une líneas con espacios:
description: >
Este es un párrafo largo
que se plegará en
una sola línea.
Añade - para eliminar saltos de línea finales (|-, >-) o + para conservarlos (|+, >+).
Un solo archivo YAML puede contener múltiples documentos separados por ---:
---
# Documento 1: Config
apiVersion: v1
kind: ConfigMap
---
# Documento 2: Service
apiVersion: v1
kind: Service
Esto se usa comúnmente en manifiestos de Kubernetes.
Dos espacios es la convención más común, utilizada por Kubernetes, Docker Compose, GitHub Actions y la mayoría de las herramientas DevOps. Algunos proyectos usan cuatro espacios. La regla clave es la consistencia dentro de un archivo — nunca mezcles niveles de indentación.
Sí, YAML soporta comentarios de una línea con #. No existe sintaxis para comentarios multilínea. Los comentarios se eliminan durante el análisis y no están disponibles en la estructura de datos cargada.
YAML es un superconjunto de JSON: cualquier JSON válido es también YAML válido. YAML está diseñado para ser más legible para los humanos, con soporte para comentarios, cadenas multilínea y anchors/aliases. JSON es más estricto, más rápido de analizar y universalmente soportado. Use YAML para archivos de configuración y JSON para APIs e intercambio de datos.
En YAML 1.1 (usado por muchos parsers incluyendo PyYAML), 'on', 'off', 'yes', 'no' son valores booleanos válidos. Esto puede causar errores cuando se usan como cadenas simples (p.ej., en Ansible). YAML 1.2 solucionó esto — solo 'true' y 'false' son booleanos. Solución: siempre entrecomille estos valores ('yes', 'no') si desea usarlos como cadenas.
Use el escalar de bloque literal (|) para preservar los saltos de línea: cada línea del bloque se convierte en un salto de línea real en la cadena. Use el escalar de bloque plegado (>) para convertir los saltos de línea en espacios: ideal para párrafos largos. Ambos admiten indicadores opcionales de chomping (- para eliminar los saltos de línea al final, + para mantenerlos todos).
YAML usa espacios para la sangría — nunca tabulaciones. Todas las claves hermanas deben estar en el mismo nivel de sangría. Mezclar tabulaciones y espacios siempre causará errores. Soluciones comunes: active la configuración 'reemplazar tabulaciones con espacios' en su editor, use un linter (yamllint), asegure una anchura de sangría consistente (2 o 4 espacios) en todo el archivo.