Primeros pasos
Estructura básica
YAML usa la indentación (espacios, nunca tabuladores) para anidar. Los mapeos usan clave: valor y las secuencias usan - elemento. La sintaxis en línea usa [] para listas y {} para mapas. Los comentarios usan #.
# YAML uses indentation for structure
# Comments start with #
# Key-value pairs (mappings)
name: Alice
age: 30
# Nested mappings (use consistent indentation)
person:
name: Bob
age: 25
address:
city: NYC
zip: 10001
# Sequences (lists)
hobbies:
- reading
- coding
- music
# Inline syntax
numbers: [1, 2, 3]
coords: {x: 10, y: 20}Comentarios
Los comentarios empiezan con # y deben ir precedidos de un espacio o del inicio de línea. Dentro de los escalares de bloque (| y >), el # es contenido literal, no un comentario. No existe sintaxis de comentario multilínea: cada línea necesita su propio #.
# Full-line comment
key: value # Inline comment (whitespace before # required)
# Comments can appear anywhere
# - before documents
# - inside sequences
list:
- a # first item
- b # second item
# Block scalar headers DO accept comments
text: | # literal block
line one
# But the content of block scalars is literal,
# so # inside is NOT a comment:
literal: |
# this is part of the string, not a commentReglas de indentación
YAML prohíbe terminantemente los tabuladores para indentar: solo se permiten espacios. La indentación debe ser consistente dentro de un nivel, pero no tiene que ser un número fijo. El - de las secuencias forma parte de la indentación. Mezclar tabuladores y espacios provoca un error del analizador.
# Use SPACES only — tabs are forbidden for indentation
# 2 spaces is the most common convention
mapping:
nested:
deeply_nested: value
# Sequences can be indented at the same level as the key
items:
- one
- two
# Or indented further (both are valid)
items2:
- one
- two
# WRONG: tab characters cause parser errors
# bad: value (tab before value)
# Hyphen counts as indentation start
- item1
- item2Inicio y fin de documento
--- marca el inicio de un documento YAML y ... su fin. Un archivo puede contener varios documentos separados por --- (un flujo de documentos). En archivos de configuración de un solo documento, el --- inicial es opcional pero se recomienda como pista para los analizadores.
# --- separates documents in a stream
# ... ends a document (optional)
---
name: first document
value: 1
...
---
name: second document
value: 2
...
# A single document needs no markers
key: value
# But --- is recommended at the start of files
# to disambiguate from plain text
---
apiVersion: v1
kind: ConfigMapErrores comunes
Los dos puntos necesitan un espacio después para ser un separador de mapeo. YAML 1.1 y 1.2 difieren en yes/no/on/off (booleanos en 1.1, cadenas en 1.2) y en los literales octales. Los valores vacíos son null, distinto de una cadena vacía. Muchos analizadores (PyYAML) todavía siguen las reglas de 1.1.
# Colon needs a space after it
key:value # WRONG: parsed as a single string "key:value"
key: value # correct
# Yes/No/On/Off are NOT booleans in YAML 1.2
# (they WERE in YAML 1.1 — common gotcha)
answer: yes # YAML 1.1: true; YAML 1.2: "yes" string
# Numbers with leading zeros
version: 010 # YAML 1.1: octal 8; YAML 1.2: string "010"
# Unquoted strings with special chars
url: example.com/path # OK
url: example.com:8080 # WRONG: parsed as mapping with key example.com
# Empty values
empty: # null
empty2: ~ # explicit null
empty3: "" # empty string (different from null)YAML frente a JSON
YAML 1.2 se diseñó para que JSON fuera un subconjunto estricto: cualquier archivo JSON es YAML válido. YAML añade comentarios, estructura de bloque, anclas, cadenas multilínea y etiquetas. JSON exige entrecomillar todas las claves y valores de cadena, algo que YAML relaja para los escalares planos.
# JSON is a strict subset of YAML 1.2
# Every valid JSON document is valid YAML
# JSON:
{"name": "Alice", "age": 30, "hobbies": ["a", "b"]}
# Equivalent YAML:
name: Alice
age: 30
hobbies:
- a
- b
# YAML adds: comments, multi-line strings, anchors,
# relaxed quoting, tags, multiple documents
# YAML removes: mandatory quotes around strings,
# commas, braces (in block style)
# YAML is a superset of JSON — not the other way.
# Comments and anchors are not valid JSON.Escalares (cadenas, números, booleanos, null)
Cadenas planas y entrecomilladas
Las cadenas planas no necesitan comillas salvo que parezcan números, booleanos, null o fechas. Las comillas simples solo escapan ' duplicándola (''); no hay más escapes. Las comillas dobles soportan secuencias de escape completas (\n, \t, \uXXXX). Entrecomillar fuerza el tipo cadena.
# Plain strings (no quotes) — most common
name: Alice
path: /usr/local/bin
url: https://example.com
# Single-quoted — escape ' by doubling
msg: 'it''s fine'
# Double-quoted — supports escapes
greeting: "Hello\nWorld"
unicode: "\u03B1" # Greek alpha
tab: "col1\tcol2"
# Multi-word plain strings are fine
description: This is a plain string with spaces
# Strings that look like other types must be quoted
version: "1.0" # string, not float
notBool: "true" # string, not boolean
notNull: "null" # string, not null
date: "2024-01-01" # string, not dateNúmeros
YAML 1.2 usa 0o para octal (YAML 1.1 usaba un 0 inicial suelto). Los guiones bajos en los números están permitidos por legibilidad. .inf y .nan son literales flotantes especiales. Entrecomilla cualquier valor que deba ser cadena pero parezca numérico (versiones, teléfonos, IDs).
# Integers
int: 42
negative: -17
positive: +100
underscored: 1_000_000 # readable grouping (YAML 1.2)
# Octal & hex (YAML 1.2 prefixes)
octal: 0o17 # = 15 decimal
hex: 0xFF # = 255 decimal
binary: 0b1010 # = 10 decimal
# Floats
pi: 3.14159
exp: 1.0e+3 # 1000.0
neg_exp: -2.5e-4
# Special float values (IEEE 754)
infinity: .inf
neg_infinity: -.inf
not_a_number: .nan
# To force a string that looks numeric:
version: "1.0"
phone: "555-1234"Booleanos
YAML 1.2 redujo los booleanos a true/false (y True/False, TRUE/FALSE). YAML 1.1 (el que usa PyYAML) trata yes/no/on/off/y/n como booleanos, una fuente famosa de errores (por ejemplo, el 'no' de Noruega → false). Entrecomilla siempre estas cadenas si las quieres literales.
# YAML 1.2 — only these are booleans:
enabled: true
disabled: false
# YAML 1.1 ALSO accepts (common gotcha):
# yes, no, on, off, y, n, Y, N
# These are strings in 1.2 but booleans in 1.1
# To force a string:
answer: "yes" # always a string
option: "on"
flag: "y"
# PyYAML (1.1 rules) parses these as booleans:
# yes -> True, no -> False, on -> True, off -> False
# This breaks "no" as an answer or country code!
# Safe practice: quote if you mean the literal string
country: "no" # Norway country code, not FalseValores null
YAML acepta null, Null, NULL, ~ y un valor vacío como null. Un valor vacío (una clave sin nada tras los dos puntos) es null, distinto de una cadena vacía "". Los analizadores mapean el null de YAML al valor nulo del lenguaje anfitrión (None, null, nil).
# All of these represent null/None/null
key1: null
key2: Null
key3: NULL
key4: ~
key5: # empty value
# Distinguish null from empty string
empty_string: ""
null_value: null
# In sequences
list:
- value
- null # explicit null item
- another
# In nested structures
config:
timeout: null # explicitly unset
retries: 3
# Parsers convert to language-specific null:
# Python -> None, JavaScript -> null, Go -> nilFechas y marcas de tiempo
Las fechas y marcas de tiempo ISO 8601 se reconocen como tipos nativos en la mayoría de analizadores. Un YYYY-MM-DD suelto se convierte en fecha; con hora, en fecha-hora. Entrecomilla el valor para mantenerlo como cadena. Se admiten designadores de zona horaria (Z, +08:00).
# Date (ISO 8601)
date: 2024-01-15
# Datetime (ISO 8601)
datetime: 2024-01-15T14:30:00
datetime_tz: 2024-01-15T14:30:00Z
datetime_offset: 2024-01-15T14:30:00+08:00
datetime_space: 2024-01-15 14:30:00
# To force string (not a date):
not_a_date: "2024-01-15"
not_a_date2: '2024-01-15'
# Parsers typically return datetime objects
# Python: datetime.date / datetime.datetime
# JavaScript: Date (depending on library)Inferencia de tipos
El sistema de tipos de YAML resuelve los escalares sin comillas mediante un esquema. El esquema Failsafe trata la totalidad como cadenas; los esquemas JSON y Core infieren int, float, bool, null y date. Usa comillas o etiquetas explícitas (!!str, !!int) para anular la resolución cuando haga falta.
# YAML infers types from unquoted scalars
str: hello # string
int: 42 # integer
float: 3.14 # float
bool: true # boolean
null_val: null # null
date: 2024-01-01 # date
list: [1, 2, 3] # sequence
# Force string type with quotes
str_version: "42"
str_date: "2024-01-01"
str_bool: "true"
# Or with the !!str tag
forced: !!str 42 # string "42"
forced_int: !!int "42" # integer 42
# Resolution depends on the schema
# Failsafe: everything is a string
# JSON/Core: numbers, bools, null inferredMapeos
Mapeo simple
Un mapeo son pares clave: valor donde las claves suelen ser cadenas. Las claves pueden ser cualquier escalar (número, bool, incluso null). Las claves duplicadas están desaconsejadas y el comportamiento varía según el analizador (a menudo gana la última). Usa un linter para detectar duplicados accidentales.
# A mapping is a set of key: value pairs
name: Alice
age: 30
email: [email protected]
# Keys can be any scalar type (string, number, bool)
"string key": value
123: numeric key
true: boolean key
# Duplicate keys are technically discouraged
# but some parsers allow them (last wins)
key: first
key: second # overrides "first" in many parsers
# Values can be any type
mixed:
string: text
number: 42
list: [1, 2, 3]
nested:
deep: valueMapeos anidados
Los mapeos anidados se crean indentando las claves hijas. La indentación debe ser consistente dentro de un nivel. No hay un tamaño fijo de indentación, pero 2 espacios es el estándar de facto. El anidamiento profundo reduce la legibilidad: considera aplanar las estructuras muy profundas.
# Nest mappings with consistent indentation
server:
host: localhost
port: 8080
ssl:
enabled: true
cert: /etc/ssl/cert.pem
key: /etc/ssl/key.pem
database:
primary:
host: db1.example.com
port: 5432
replica:
host: db2.example.com
port: 5432
# Indentation level is up to you — just be consistent
# 2 spaces is the most common conventionMapeo de secuencias
Mapeos y secuencias se componen libremente. Un patrón habitual es la secuencia de mapeos (una lista de registros), donde cada - inicia un elemento y las claves alineadas pertenecen a ese elemento. La indentación de las claves siguientes debe alinearse con la primera clave tras el -.
# Values in a mapping can be sequences
servers:
- web1.example.com
- web2.example.com
- web3.example.com
# Sequence of mappings (very common)
users:
- name: Alice
age: 30
- name: Bob
age: 25
# Each - starts a new item; aligned keys form one mapping
services:
- name: api
port: 8080
env:
- dev
- prod
- name: web
port: 3000
# Mixed: mapping containing sequence containing mapping
config:
endpoints:
- path: /health
method: GET
- path: /users
method: POSTClaves complejas
YAML permite cualquier escalar o colección como clave usando el indicador ? clave. Es raro en archivos de configuración pero útil para tablas de búsqueda (por ejemplo, precios por región+instancia). Las claves complejas son incómodas de leer: la mayoría de archivos de configuración se atienen a claves de cadena planas.
# Keys can be complex objects using ? notation
? key1
: value1
# A mapping as a key
? host: localhost
port: 8080
: connection1
# A sequence as a key
? [a, b, c]
: indexed_value
# Practical (rare) use: matrix lookup
? [us-east-1, t2.micro]
: 0.0116
? [us-east-1, t2.small]
: 0.023
# In flow style:
{[a, b]: value, {x: 1}: other}
# Most config files just use plain string keys
simple: valueMapeos en línea (flow)
El estilo flow usa {} para mapeos y [] para secuencias, parecido a JSON. Útil para datos cortos y compactos en una línea. A diferencia de JSON, YAML no permite comas finales. Mezcla estilos flow y de bloque libremente, pero prefiere el bloque por legibilidad en archivos de configuración.
# Flow style mapping (like JSON)
point: {x: 10, y: 20}
config: {host: localhost, port: 8080}
# Nested flow mappings
nested: {a: {b: {c: value}}}
# Mixed flow and block
block_key:
flow_value: {x: 1, y: 2}
another: value
# Flow with sequences
mixed: {nums: [1, 2, 3], name: test}
# Quoting still works in flow style
quoted: {"key with space": "value", count: 3}
# Trailing comma is NOT allowed in YAML flow
bad: {a: 1, b: 2,} # parse errorOrden de claves y estilo
La propia especificación de YAML preserva el orden de los mapeos, pero los objetos del lenguaje anfitrión pueden no hacerlo (aunque la mayoría de diccionarios modernos sí). Para que la configuración sea legible, agrupa claves relacionadas, usa un nombrado consistente (snake_case o camelCase) y añade comentarios que delimiten las secciones.
# YAML mappings are ORDERED (unlike JSON spec, though
# most JSON parsers preserve insertion order too)
# But language objects may not preserve order:
# Python dict (3.7+): preserves order
# Ruby Hash: preserves order
# JSON object: technically unordered
# Consistent key style improves readability
config:
server:
host: localhost # snake_case
port: 8080
max_connections: 100
database:
host: db.example.com
port: 5432
connection_pool: 10
# Group related keys together
# Use comments to delineate sections
app:
# networking
host: 0.0.0.0
port: 3000
# limits
timeout: 30
retries: 3Secuencias
Secuencias de bloque
Las secuencias de bloque usan - (guion + espacio) antes de cada elemento. Los elementos pueden ser de cualquier tipo: escalares, mapeos o secuencias anidadas. El - cuenta como parte de la indentación, así que las claves siguientes de un elemento de mapeo se alinean con la primera clave tras el guion.
# A sequence (list) uses - followed by space
fruits:
- apple
- banana
- cherry
# Sequence as top-level document
- item1
- item2
- item3
# Empty sequence
empty: []
or_with_marker: []
# Sequence with mixed types
mixed:
- string
- 42
- true
- null
- key: value # a mapping as an itemSecuencias anidadas
Las secuencias anidadas se forman indentando otros niveles de -. Pasados 2 niveles se vuelven difíciles de leer: pasa a estilo flow para las secuencias interiores. Las estructuras de árbol (secuencia de mapeos con children) son más legibles que las secuencias puramente anidadas.
# Sequence of sequences
matrix:
- - 1
- 2
- 3
- - 4
- 5
- 6
# More readable with flow style for inner
matrix2:
- [1, 2, 3]
- [4, 5, 6]
# Deeply nested
tree:
- name: root
children:
- name: child1
children:
- name: grandchild1
- name: child2
# 3D: sequence of sequence of sequence
cube:
- - [1, 2]
- [3, 4]
- - [5, 6]
- [7, 8]]Secuencia de mapeos
Una secuencia de mapeos es el patrón YAML más común (listas de registros). Cada - inicia un elemento nuevo; las claves siguientes a la misma indentación pertenecen a ese elemento. Alinea las claves después del - por legibilidad. Un elemento de mapeo vacío se escribe {}.
# Most common pattern: list of records
users:
- name: Alice
email: [email protected]
roles:
- admin
- user
- name: Bob
email: [email protected]
roles:
- user
# Each - starts a new mapping; aligned keys belong
# to that item. Indent the first key after - by 2 spaces.
servers:
- host: web1.example.com
port: 8080
healthy: true
- host: web2.example.com
port: 8080
healthy: false
# Empty mapping item
list:
- {}
- name: realSecuencias en línea (flow)
Las secuencias flow usan [] y equivalen a las de bloque. Útiles para listas cortas en una línea. Las secuencias flow pueden ocupar varias líneas por legibilidad. A diferencia de JSON, YAML prohíbe las comas finales. Mezcla secuencias flow con mapeos de bloque sin problema.
# Flow sequence (JSON-like)
numbers: [1, 2, 3]
names: [Alice, Bob, Charlie]
# Nested flow sequences
matrix: [[1, 2], [3, 4]]
# Flow sequence of flow mappings
points: [{x: 1, y: 2}, {x: 3, y: 4}]
# Mixed: block mapping with flow sequence value
config:
ports: [80, 443, 8080]
hosts: [web1, web2, web3]
# Spread across multiple lines (still flow style)
long_list: [
item1,
item2,
item3
]
# NO trailing comma allowed
bad: [1, 2, 3,] # errorContenido mixto y heterogéneo
YAML permite contenido completamente heterogéneo en secuencias y mapeos: cualquier elemento puede ser de cualquier tipo. Esta flexibilidad es potente, pero implica que la aplicación debe validar la estructura. Usa un esquema (JSON Schema, Cue, etc.) para una validación estricta.
# Sequences can mix types freely
mixed:
- string
- 42
- true
- null
- [1, 2, 3] # nested sequence
- key: value # mapping
another: value2
- - nested
- sequence
# Heterogeneous mapping values
config:
string_val: text
int_val: 42
list_val: [a, b, c]
map_val: {x: 1, y: 2}
null_val: null
bool_val: true
# YAML has no schema enforcing uniformity —
# the application must validate structurePatrones de indentación de secuencias
Las secuencias bajo una clave pueden ir indentadas (Patrón 1) o al mismo nivel (Patrón 2, ya que el - cuenta como indentación). Ambas formas son válidas; elige una y sé consistente. En secuencias de mapeos, todas las claves de un elemento deben alinearse con la primera clave tras el -.
# Pattern 1: sequence indented under key
items:
- a
- b
# Pattern 2: sequence at same level as key
# (the - is treated as indentation)
items:
- a
- b
# Both are valid and produce the same result.
# Pick one and be consistent (most style guides prefer #1).
# Mapping item alignment — both keys align with first
users:
- name: Alice
age: 30
- name: Bob
age: 25
# WRONG: misaligned keys cause parse errors
# users:
# - name: Alice
# age: 30 # one space off — errorCadenas multilínea (plegadas y literales)
Escalar de bloque literal (|)
El escalar de bloque literal | preserva cada salto de línea exactamente como está escrito. La indentación (la cantidad a partir del |) se elimina de cada línea. El chomping por defecto (clip) conserva un salto de línea final. Se usa para scripts, código, poesía, arte ASCII: en cualquier lugar donde importen los saltos literales.
# | preserves newlines as-is
script: |
#!/bin/bash
echo "Hello"
echo "World"
# Output string:
# #!/bin/bash\necho "Hello"\necho "World"\n
poem: |
Roses are red,
Violets are blue,
YAML is clean,
And JSON is too.
# Trailing newline is kept by default (clip mode)
# Use |- to strip, |+ to keep all trailing newlinesEscalar de bloque plegado (>)
El escalar de bloque plegado > convierte los saltos de línea simples en espacios, uniendo las líneas en párrafos. Las líneas en blanco se convierten en saltos de línea literales. Las líneas más indentadas que el contenido del bloque se preservan literalmente (útil para ejemplos de código dentro de prosa).
# > folds newlines into spaces (paragraphs)
description: >
This is a long paragraph that
spans multiple lines in the YAML
but will be joined into one line
when parsed.
# Output: "This is a long paragraph that spans multiple
# lines in the YAML but will be joined into one line when
# parsed.\n"
# Blank lines preserve a newline
paragraphs: >
First paragraph here.
Second paragraph here.
Third paragraph here.
# More indented lines are preserved literally
example: >
This is folded.
This line is more indented — kept literal.Indicadores de chomping (+/-)
El chomping controla los saltos de línea finales: clip (por defecto, sin indicador) conserva uno; strip (-) los elimina en su totalidad; keep (+) los conserva en su totalidad. El indicador va justo después de | o > (por ejemplo |-, |+, >-, >+). Strip es útil para cadenas usadas en línea; keep es raro pero reproduce la fuente exactamente.
# Default (clip): single trailing newline
text: |
line1
line2
# Result: "line1\nline2\n"
# Strip (-): remove ALL trailing newlines
text_strip: |-
line1
line2
# Result: "line1\nline2"
# Keep (+): keep ALL trailing newlines
text_keep: |+
line1
line2
# Result: "line1\nline2\n\n\n"
# Same applies to folded scalars
folded_keep: >+
folded
text
Indicador de indentación
Cuando el contenido de un escalar de bloque empieza con espacios en blanco, debes especificar explícitamente la indentación del contenido con un dígito (por ejemplo |2). El dígito indica cuántos espacios de indentación pertenecen a la estructura y cuántos al contenido. Combínalo con chomping: |2-, >4+, etc. Rara vez hace falta, pero es imprescindible cuando así es.
# When the first line starts with spaces, you must
# tell YAML the content indentation explicitly
# Without indicator (ambiguous):
# content:
# indented_line # is the leading space content or not?
# With explicit indentation indicator (digit after | or >)
literal: |2
hello
world
# The "2" means: content is indented 2 spaces past the indicator
# So 4 spaces of indentation = 2 content + 2 extra
# Combined with chomping (order: indent then chomp)
text: |2-
no trailing newline
# Folded with explicit indent
folded: >4
paragraph with
explicit indent
# Most of the time you don't need this — only when
# content legitimately starts with spacesCadenas multilínea planas
Los escalares planos y entrecomillados pueden abarcar varias líneas, con los saltos plegados en espacios (parecido a > pero implícito). Es frágil porque los saltos dependen del contexto y de los caracteres especiales. Para cualquier texto multilínea que no sea trivial, prefiere los escalares de bloque explícitos | (literal) o > (plegado).
# Plain (unquoted) scalars can span lines
# Newlines are folded to spaces (like > but no indicator)
message: this is
a long message
on multiple lines
# Result: "this is a long message on multiple lines"
# Quotes are required if the string contains special chars
quoted: "this is also
a long message
on multiple lines"
# Result: "this is also a long message on multiple lines"
# Plain multi-line breaks at certain chars
# (colons, etc.) — usually fold cleanly
# but be careful with leading colons
# Plain is fragile for multi-line — prefer | or >
safe_literal: |
Use literal block for
predictable multi-line textElegir plegado o literal
Regla general: usa | cuando los saltos de línea sean significativos (scripts, archivos de configuración, código) y > cuando quieras una fuente multilínea legible pero un párrafo unido (descripciones, documentación). Usa |- para eliminar el salto final cuando la cadena se use en línea.
# Use | (literal) when newlines matter:
script: |
#!/bin/bash
set -e
echo "Step 1"
echo "Step 2"
config_file: |
[default]
region=us-east-1
output=json
# Use > (folded) when you want readable source
# but a single paragraph string:
description: >
This service handles user authentication
and session management. It talks to the
PostgreSQL database and Redis cache.
# Use |- or >- to strip trailing newline
# (useful for inline string usage):
inline_script: |-
echo hello
# Use plain single-line for short strings
short: hello worldAnclas y alias
Definir anclas (&)
&name define un ancla en un nodo (mapeo, secuencia o escalar). El ancla no cambia el valor en ese lugar: solo etiqueta el nodo para reutilizarlo. Los alias (*name) referencian el nodo anclado por su nombre. Las anclas deben definirse antes de usarse dentro del documento.
# &name defines an anchor on a node
defaults: &defaults
adapter: postgres
host: localhost
port: 5432
# The anchor marks the node so it can be reused
# The value is still assigned normally
production:
database: *defaults
# *defaults is an alias — references the anchored node
# Anchors on scalars
version: &ver "1.0.0"
current: *ver
# Anchors on sequences
colors: &colors
- red
- green
- blue
primary: *colorsUsar alias (*)
*name es un alias que referencia un nodo anclado previamente. Los alias comparten identidad con el original (el mismo objeto en la mayoría de analizadores). Las anclas/alias tienen ámbito de documento: no pueden referenciar a través de los límites --- de los documentos. Combínalos con << (merge key) para superponer sobrescrituras.
# Define once, reuse by alias
base: &base
image: nginx:1.25
restart: always
web:
<<: *base
ports:
- "80:80"
api:
<<: *base
ports:
- "8080:8080"
environment:
- DEBUG=true
# Aliases reference the SAME object (by identity)
# In most parsers, mutating one mutates the other
# (though YAML itself is read-only)
# Aliases can't span documents
# Each document has its own anchor namespaceÁmbito de las anclas
Las anclas tienen el ámbito de su documento y deben definirse antes de que cualquier alias las referencie (no hay referencias adelantadas). Varios alias pueden referenciar la misma ancla. Aliar un alias funciona: se resuelve de forma transitiva. Las referencias entre documentos son un error.
# Anchors are scoped to a single document
---
# Document 1
shared: &shared
key: value
use: *shared # works
...
---
# Document 2 — &shared is NOT visible here
other: *shared # ERROR: unknown anchor
# Anchors must be defined before the alias
# (forward references are not allowed)
bad: *later # ERROR
later: &later value
# Multiple aliases to the same anchor are fine
template: &tpl
timeout: 30
use1: *tpl
use2: *tpl
use3: *tpl
# Aliasing an alias is allowed
a: &a value
b: &b *a
c: *b # resolves to "value"Sobrescribir valores anclados
Un alias (*name) reemplaza el nodo entero: no se puede sobrescribir parcialmente. Para sobrescribir claves individuales de un mapeo anclado, usa la merge key << para fusionar el mapeo anclado y luego añade o sobrescribe claves. Este es el patrón canónico para componer configuraciones.
# Aliases themselves can't be partially overridden —
# an alias replaces the whole node. Use << (merge)
# to combine an anchored mapping with overrides.
defaults: &defaults
timeout: 30
retries: 3
log_level: info
production:
<<: *defaults
log_level: warn # override
host: prod.example.com # add
# Result:
# production:
# timeout: 30
# retries: 3
# log_level: warn
# host: prod.example.com
# Without <<, an alias replaces the whole node:
wrong:
thing: *defaults
# thing is the FULL defaults mapping — can't overrideAnclas en secuencias
Las anclas pueden etiquetar secuencias completas, elementos individuales de una secuencia o mapeos dentro de una secuencia. El patrón de fusión << es especialmente útil en secuencias de registros similares (por ejemplo, definiciones de servicios) para compartir campos comunes. Ancla elementos individuales con - &name valor.
# Anchors work on sequence items too
common: &common
enabled: true
log: stdout
services:
- name: web
<<: *common
port: 80
- name: api
<<: *common
port: 8080
- name: worker
<<: *common
queue: jobs
# Anchoring a whole sequence
endpoints: &endpoints
- /health
- /metrics
- /ready
monitoring:
checks: *endpoints
# Anchoring individual sequence items
list:
- &first one
- two
- *first # "one" againAdvertencias sobre las anclas
Las anclas tienen advertencias: los alias comparten identidad (mutar uno afecta a todas las referencias en analizadores mutables), añaden carga cognitiva y la mayoría de serializadores (incluida la salida JSON) los expanden a copias planas. Usa anclas para reutilización real (plantillas, valores por defecto), no para micro-optimización.
# Caveat 1: shared identity can surprise you
defaults: &defaults
list: [1, 2, 3]
a: *defaults
b: *defaults
# In mutable parsers, a.list and b.list are the SAME list.
# Editing a.list also changes b.list.
# Caveat 2: anchors add cognitive overhead
# Overuse makes YAML hard to read and trace.
# Caveat 3: not all tools preserve anchors on output
# Many serializers expand aliases to plain copies.
# Caveat 4: JSON output loses anchors entirely
# (JSON has no anchor concept).
# Caveat 5: anchors don't work across documents
---
doc1: &x value
use1: *x
---
doc2: *x # ERROR
# Prefer anchors for genuine reuse, not micro-optimization.Merge keys (<<)
Fusión básica (<<)
La merge key << toma un mapeo (normalmente un alias) y fusiona sus pares clave-valor en el mapeo actual. Las claves establecidas explícitamente en el mapeo actual sobrescriben las fusionadas. Este es el patrón canónico de herencia de configuración en YAML.
# << merges a referenced mapping into the current one
defaults: &defaults
adapter: postgres
pool: 5
timeout: 5000
development:
<<: *defaults
database: myapp_dev
host: localhost
production:
<<: *defaults
database: myapp_prod
host: db.example.com
pool: 20 # override
# Result for development:
# adapter: postgres
# pool: 5
# timeout: 5000
# database: myapp_dev
# host: localhostFusiones múltiples
<< puede fusionar varios mapeos pasando una secuencia flow de alias ([*a, *b, *c]). Las fusiones se aplican de izquierda a derecha; las posteriores sobrescriben a las anteriores para claves duplicadas. Las claves explícitas del mapeo siempre ganan sobre cualquier clave fusionada. También se permiten varias entradas <<.
# << can merge multiple mappings (sequence value)
base: &base
logging: info
retries: 3
security: &security
auth: required
tls: true
service: &service
port: 8080
host: 0.0.0.0
# Merge multiple in one go
production:
<<: [*base, *security, *service]
environment: prod
port: 80 # override service.port
# Later merges override earlier ones for the same key.
# Explicit keys always win over merges.
# You can also have multiple << entries:
combined:
<<: *base
<<: *security
custom: valueSobrescritura y precedencia
Precedencia de la fusión: las claves explícitas del mapeo siempre ganan. Entre los mapeos fusionados, los posteriores de la secuencia sobrescriben a los anteriores para la misma clave. Úsalo para superponer limpiamente defaults → específicos del rol → específicos de la instancia.
# Explicit keys override merged keys
template: &template
port: 8080
log: info
timeout: 30
instance:
<<: *template
port: 9090 # overrides template.port
log: debug # overrides template.log
host: example.com # added
# Final: {port: 9090, log: debug, timeout: 30, host: example.com}
# Precedence: explicit > later merge > earlier merge
a: &a
k: from_a
x: 1
b: &b
k: from_b
y: 2
result:
<<: [*a, *b]
k: explicit # wins over both a and b
# Final: {k: explicit, x: 1, y: 2}Patrón de fusión con anclas
El patrón fusión+ancla es el pan de cada día de Docker Compose y archivos de configuración similares: defines un ancla de defaults y luego cada servicio la fusiona y sobrescribe campos individuales. Así las configuraciones se mantienen DRY sin sacrificar la personalización por servicio.
# Common pattern: anchor templates, merge + override
defaults: &defaults
image: nginx:1.25
restart: always
logging:
driver: json-file
services:
web:
<<: *defaults
ports: ["80:80"]
api:
<<: *defaults
image: node:20 # override
ports: ["8080:8080"]
environment:
NODE_ENV: production
worker:
<<: *defaults
image: worker:latest
command: ["./run.sh"]
# This is the bread-and-butter of Docker Compose files
# — share base config, override per service.Limitaciones de la fusión
La merge key << solo funciona con mapeos: secuencias y escalares no se pueden fusionar. La fusión es superficial: un mapeo anidado en el nodo actual REEMPLAZA por completo al fusionado (no hay fusión profunda). Para fusionar en profundidad, reestructura los datos o hazlo en el código de la aplicación.
# << only works for MAPPINGS, not sequences or scalars
list_template: &list [1, 2, 3]
# This does NOT merge list items:
combined:
<<: *list # WRONG: *list is a sequence, not a mapping
extra: value # parse error or unexpected behavior
# Deep merge is NOT supported
parent: &parent
nested:
a: 1
b: 2
child:
<<: *parent
nested:
c: 3 # REPLACES parent.nested entirely
# Result: {nested: {c: 3}} — NOT {nested: {a:1, b:2, c:3}}
# To deep-merge, you must do it in application code
# or restructure the data.Estado y deprecación de la merge key
La merge key << era una extensión de YAML 1.1 eliminada de la especificación núcleo de YAML 1.2. En la práctica, la mayoría de analizadores siguen soportándola (PyYAML, js-yaml, ruamel, SnakeYAML), pero los analizadores 1.2 estrictos la rechazan. Úsala hoy, pero sabe que no es estándar; para formatos nuevos considera lenguajes de configuración con herencia real (Cue, Jsonnet, Dhall).
# IMPORTANT: the << merge key was REMOVED in YAML 1.2
# It was a YAML 1.1 feature.
# In practice, many parsers still support it:
# - PyYAML: supports (1.1 mode)
# - js-yaml: supports (opt-in)
# - ruamel.yaml: supports
# - SnakeYAML: supports
# - LibYAML: supports
# But strict YAML 1.2 parsers reject it:
# new_yaml_1_2_strict:
# <<: *template # ERROR in strict 1.2
# Recommendation:
# - Use << for now (widely supported)
# - Document that your files rely on it
# - For new formats, consider composition in code
# or a config language with proper inheritance
# (e.g. Dhall, Cue, Jsonnet)
# Alternative without <<:
# just duplicate or use application-level templatingMarcadores de documento y directivas
Documento único
Un documento YAML único funciona bien sin ningún marcador. Un --- inicial es una convención para señalar 'esto es YAML' y desambiguar del texto plano. El marcador de fin ... es opcional y rara vez se usa en archivos de un solo documento.
# A single YAML document needs no markers
key: value
list:
- a
- b
# But a leading --- is a common convention
# to mark "this is YAML, not plain text"
---
key: value
# The trailing ... (end marker) is optional
# for a single document
key: value
...Varios documentos (flujo)
Un flujo YAML es una secuencia de documentos separados por ---. Cada documento se parsea de forma independiente. Los flujos son comunes en Kubernetes (varios objetos por archivo), generadores de sitios estáticos y archivos de log. Usa load_all() o el equivalente en tu analizador para iterar los documentos.
# A YAML stream is multiple documents separated by ---
---
name: first
value: 1
---
name: second
value: 2
---
name: third
value: 3
# Each document is independent — anchors don't cross
# Use a parser's load_all() / load_multi() to read them
# Python (PyYAML):
# for doc in yaml.safe_load_all(stream):
# print(doc)
# Common use cases:
# - Kubernetes: multiple objects in one file
# - Blog generators: front matter + content
# - Log files: one record per document
# - CI/CD: multi-step pipelinesMarcador de fin de documento (...)
El marcador ... termina explícitamente un documento. Es opcional en la mayoría de casos, pero útil cuando el contenido podría ser ambiguo (por ejemplo, un bloque literal que contiene ---). También señala el fin de documento a los analizadores en streaming. Raro en YAML escrito a mano, común en la salida programática.
# ... explicitly ends a document
---
key: value
...
# Anything after ... is a new document or stream end
# Useful when a document's content might be ambiguous
# without an explicit end:
---
message: |
Some content
---
that looks like a separator
...
---
next: document
# Without ... the parser might think the ---
# inside the literal block is a document separator
# (though block scalars usually prevent this)
# ... is also useful in programmatic output to flushDirectivas
Las directivas aparecen antes del contenido del documento y configuran el analizador. %YAML fija la versión; %TAG declara atajos de prefijos de etiquetas. Las directivas tienen ámbito de documento: solo se aplican al documento siguiente. La mayoría de archivos de configuración las omiten y se apoyan en los valores por defecto del analizador (normalmente bimodal 1.1 o 1.2).
# Directives appear at the very top, before content
# %YAML — declare YAML version
%YAML 1.2
---
key: value
# %TAG — declare a tag prefix
%TAG !e! tag:example.com,2024:
---
data: !e!custom value
# Multiple directives are allowed
%YAML 1.2
%TAG !e! tag:example.com,2024:
%TAG !yaml! tag:yaml.org,2002:
---
value: !yaml!str hello
# Directives are document-scoped — they apply to the
# next document only and must be repeated for each.
# Most config files omit directives and use defaults.Ejemplos de flujos de documentos
Los flujos de documentos se usan mucho. Kubernetes los emplea para agrupar varios objetos (Namespace, Deployment, Service) en un archivo. Las plantillas de Helm, los logs de CI y los generadores de sitios estáticos (front matter + contenido) también usan flujos. Cada documento es independiente y puede tener sus propias directivas.
# Kubernetes multi-object file
---
apiVersion: v1
kind: Namespace
metadata:
name: production
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: api
namespace: production
spec:
replicas: 3
---
apiVersion: v1
kind: Service
metadata:
name: api
namespace: production
spec:
ports:
- port: 80
# Helm chart templates: stream of objects
# CI logs: one event per document
# Static site generator: front matter + bodyPeligros en los límites
Una línea que empieza por --- en la columna 0 es siempre un separador de documentos (fuera de los escalares de bloque). Dentro de los escalares de bloque (|, >), --- es contenido literal. Para incluir --- en la columna 0 dentro de un valor, indenta el bloque o termina el documento con ... antes. Un --- con contenido en la misma línea es un marcador de inicio de documento, no un separador.
# A line starting with --- is ALWAYS a document separator
# (when at column 0). This can surprise you:
---
script: |
echo hello
--- # this is INSIDE the block scalar — safe
next: value
# But this is NOT safe:
---
content: |
line1
---
mistaken: this is a NEW document, not part of content!
# Inside block scalars, --- is literal (good).
# Outside, --- at column 0 always separates documents.
# Workaround for content that must contain --- at col 0:
# indent the block, or use ... to end the doc first.
# Also: a bare --- line with content on the same line
# is the document start marker, NOT a separator
--- key: value # this is one documentEstilo flow
Secuencias flow
Las secuencias flow usan [ ] y se comportan como arrays de JSON. Los espacios y saltos interiores son flexibles. A diferencia de JSON, las comas finales NO están permitidas. Útiles para listas cortas y densas. Entrecomilla los elementos con caracteres especiales (comas, corchetes, dos puntos).
# Flow sequences use [item1, item2, ...]
numbers: [1, 2, 3]
names: [Alice, Bob, Charlie]
# Empty
empty: []
# Nested flow sequences
matrix: [[1, 2], [3, 4]]
# Flow sequence of mappings
points: [{x: 1, y: 2}, {x: 3, y: 4}]
# Multi-line flow sequence (whitespace is flexible)
long: [
alpha,
beta,
gamma
]
# Quoting inside flow
mixed: ["hello", 'world', 42, true]
# NO trailing comma
bad: [1, 2, 3,] # parse errorMapeos flow
Los mapeos flow usan { } y se comportan como objetos JSON. Las claves pueden entrecomillarse si contienen caracteres especiales. Los espacios son flexibles. Las comas finales están prohibidas (a diferencia de JSON). Usa mapeos flow para datos cortos y densos; el estilo de bloque es más legible para estructuras mayores.
# Flow mappings use {key: value, ...}
point: {x: 10, y: 20}
config: {host: localhost, port: 8080}
# Empty mapping
empty: {}
# Nested flow mappings
nested: {a: {b: {c: value}}}
# Quoted keys (needed for special chars)
quoted: {"key with space": value, "weird:key": 1}
# Multi-line flow mapping
config: {
host: localhost,
port: 8080,
debug: true
}
# Flow mapping with flow sequence value
mixed: {nums: [1, 2, 3], name: test}
# NO trailing comma
bad: {a: 1, b: 2,} # parse errorMezclar flow y bloque
Los estilos flow y de bloque pueden mezclarse libremente dentro de un documento. La regla pragmática: usa bloque para los elementos estructurales (mejor legibilidad con indentación) y flow para valores cortos en línea (listas de escalares, mapas pequeños). Evita el flow profundamente anidado: se vuelve ilegible enseguida.
# Mix flow and block styles freely
config:
name: myapp
ports: [80, 443] # flow sequence in block mapping
endpoints: {api: /v1, web: /} # flow mapping in block
# Block inside flow (less common but valid)
flow_with_block: [{name: Alice, roles: [admin, user]}, {name: Bob}]
# Flow at top level
[top, level, flow]
# Block at top level
- block
- sequence
# Pragmatic rule:
# - Block for structure (readability)
# - Flow for short inline values
# - Avoid deeply nested flow — it becomes unreadableFlow anidado
El estilo flow puede anidarse a cualquier profundidad, pero cada nivel añade corchetes/llaves que se vuelven difíciles de leer. Tras 1-2 niveles de anidamiento, pasa a estilo de bloque por legibilidad. El equivalente de bloque de un flow profundamente anidado casi siempre es más claro para los mantenedores humanos.
# Flow can nest arbitrarily
data: {users: [{name: Alice, tags: [a, b]}, {name: Bob}]}
# Equivalent block:
# data:
# users:
# - name: Alice
# tags:
# - a
# - b
# - name: Bob
# Multi-line nested flow (rare but valid)
matrix: {
rows: [
[1, 2, 3],
[4, 5, 6]
],
cols: 3
}
# Recommendation: switch to block style after 1-2 levels
# of nesting — flow becomes a "wall of brackets".Cuándo usar el estilo flow
Usa el estilo flow para listas cortas de escalares, mapas de búsqueda pequeños, registros de una línea y salida compatible con JSON. Evita flow para listas largas (difíciles de ojear), estructuras profundamente anidadas (muro de corchetes) o cualquier cosa que necesite comentarios en línea. Ante la duda, prefiere el bloque por legibilidad.
# Good uses of flow style:
# 1. Short lists of scalars
ports: [80, 443, 8080]
colors: [red, green, blue]
# 2. Small lookup maps
codes: {200: OK, 404: NotFound, 500: Error}
# 3. Single-line records in a sequence
coordinates:
- {x: 1, y: 2}
- {x: 3, y: 4}
- {x: 5, y: 6}
# 4. JSON-compatible output (flow is JSON-compatible)
# Bad uses of flow style:
# 1. Long lists (use block)
# ports: [80, 443, 8080, 8443, 9000, 9090, 9091, ...] # hard to read
# 2. Deeply nested (use block)
# {a: {b: {c: {d: {e: value}}}}} # unreadable
# 3. Anything with comments (flow doesn't allow inline comments well)Advertencias del estilo flow
El estilo flow tiene advertencias: los caracteres especiales (comas, dos puntos, corchetes) necesitan comillas; no hay comas finales; los comentarios resultan incómodos; no hay escalares de bloque | ni > (usa \n en cadenas entre comillas dobles); y los cambios de una sola línea son más difíciles de diferenciar. El estilo de bloque es más amigable para configuración versionada.
# Caveat 1: special characters need quotes in flow
flow: [a, b, "c,d", "d:e"] # commas and colons need quoting
block:
- a
- b
- c,d # no quotes needed in block style
- d:e # no quotes needed in block style
# Caveat 2: no trailing commas
bad: [1, 2, 3,] # error
# Caveat 3: comments are awkward in flow
config: {
host: localhost, # comment allowed but clunky
port: 8080
}
# Caveat 4: flow style has no multi-line strings
# (no | or > inside flow)
# You can use \n escapes in double quotes:
text: "line1\nline2"
# Caveat 5: flow is harder to diff in version control
# (one-line changes vs whole-block changes)Conversión entre YAML y JSON
JSON es YAML válido
YAML 1.2 se diseñó para que JSON fuera un subconjunto estricto: cualquier documento JSON es YAML válido. La mayoría de analizadores YAML leen JSON sin problema. Al revés no es cierto: características de YAML como comentarios, anclas, flujos multidocumento y escalares de bloque no son JSON válido.
# JSON is a strict subset of YAML 1.2
# Any JSON file is valid YAML
# This is valid YAML (it's JSON):
{"name": "Alice", "age": 30, "hobbies": ["a", "b"]}
# So is this multi-line JSON:
{
"name": "Alice",
"age": 30,
"hobbies": ["a", "b"]
}
# Parsers usually accept JSON files as YAML
# Python: yaml.safe_load(json_string) # works
# JS: YAML.load(json_string) # works
# Go: yaml.Unmarshal(json_bytes, &v) # works (yaml.v3)
# But the reverse is NOT always true:
# YAML with comments, anchors, multi-docs is NOT valid JSONRepresentaciones equivalentes
JSON, YAML de bloque y YAML flow pueden representar los mismos datos. JSON es el más portable (cada lenguaje tiene un parser JSON). YAML de bloque es el más legible para humanos. YAML flow es un término medio compacto. Elige según tu audiencia: herramientas (JSON) frente a humanos (YAML de bloque).
# JSON:
{"name": "Alice", "age": 30, "hobbies": ["a", "b"]}
# YAML block:
name: Alice
age: 30
hobbies:
- a
- b
# YAML flow (closest to JSON):
{name: Alice, age: 30, hobbies: [a, b]}
# YAML with quotes (JSON-compatible):
{"name": "Alice", "age": 30, "hobbies": ["a", "b"]}
# All four parse to the same data structure.
# Pick the style that fits your use case:
# - JSON for interop and strict tools
# - YAML block for human-edited config
# - YAML flow for compact inline dataConversión de JSON a YAML
Convierte JSON a YAML parseando el JSON y volcándolo como YAML con default_flow_style=False (estilo de bloque). Las comillas obligatorias de JSON se eliminan donde YAML no las necesita. Ojo con las claves que parecen números/booleanos: pueden necesitar comillas en YAML para conservar el tipo cadena.
# Convert JSON to YAML using a parser
# Python:
# import json, yaml
# data = json.loads(json_string)
# yaml_str = yaml.safe_dump(data, default_flow_style=False, sort_keys=False)
#
# JS:
# const data = JSON.parse(jsonString)
# const yamlStr = yaml.dump(data)
# Example input JSON:
# {"server": {"host": "localhost", "port": 8080}, "debug": true}
# Output YAML:
# server:
# host: localhost
# port: 8080
# debug: true
# Conversion considerations:
# - JSON keys are always quoted -> YAML usually unquotes them
# - JSON arrays -> YAML block sequences (with default_flow_style=False)
# - JSON strings with special chars may need quoting
# - JSON null -> YAML null (or ~)
# - JSON booleans/numbers preservedConversión de YAML a JSON
Convierte YAML a JSON parseando y serializando a JSON. Advertencias: los comentarios y etiquetas se pierden; las anclas se expanden a copias planas; los flujos multidocumento deben convertirse en un array JSON; las fechas YAML pueden volverse cadenas. Herramientas como yq lo hacen fácil en la línea de comandos.
# Convert YAML to JSON
# Python:
# import json, yaml
# data = yaml.safe_load(yaml_string)
# json_str = json.dumps(data, indent=2)
# JS:
# const data = yaml.load(yamlString)
# const jsonStr = JSON.stringify(data, null, 2)
# Command-line tools:
# yq -o=json '.config' file.yaml # mikefarah/yq
# ruby -ryaml -rjson -e 'puts JSON.generate(YAML.load(STDIN.read))' < file.yaml
# python -c 'import json,sys,yaml; print(json.dumps(yaml.safe_load(sys.stdin)))'
# Caveats when converting YAML to JSON:
# - YAML comments are LOST (JSON has no comments)
# - YAML anchors are EXPANDED to plain copies
# - YAML multi-doc streams become a JSON array (or fail)
# - YAML tags (!!) are lost or cause errors
# - YAML dates may become strings (JSON has no date type)Subconjunto compatible con JSON
El subconjunto de YAML compatible con JSON evita comentarios, anclas, multidocumento, etiquetas, escalares de bloque y cadenas planas que parezcan de otro tipo. Quedarse en este subconjunto garantiza idas y vueltas limpias a JSON. Útil cuando consumidores YAML y JSON leen los mismos datos, o cuando la preservación estricta de tipos importa.
# To produce YAML that round-trips to JSON cleanly,
# stay within the JSON-compatible subset:
# 1. No comments
# 2. No anchors/aliases
# 3. No multi-doc streams
# 4. No tags
# 5. No block scalars (|, >) — use \n in double-quoted strings
# 6. Quote all string keys (JSON requires this)
# 7. No plain strings that look like other types
# JSON-compatible YAML:
{"name": "Alice", "age": 30, "active": true}
{"items": ["a", "b", "c"]}
{"nested": {"key": "value"}}
# Useful when you need both YAML and JSON consumers
# for the same data, or want strict type preservation.
# Many YAML dumpers have a "json-compatible" mode.Consideraciones sobre el round-trip
El round-trip de YAML (parsear y volver a volcar) suele perder comentarios, nombres de anclas, orden de claves, estilo de comillas y formato. ruamel.yaml (Python) tiene un modo round-trip que preserva comentarios y orden. Para configuración editada por humanos, nunca sobrescribas a ciegas con la salida del dumper: compara las diferencias con cuidado primero.
# Round-trip: YAML -> parse -> dump -> YAML
# Information that may be LOST:
# - Comments (most dumpers drop them)
# - Anchor names (dumpers may re-create or expand)
# - Key order (some dumpers sort keys)
# - Quoting style (dumpers choose their own)
# - Flow vs block style (dumpers usually pick one)
# - Whitespace and indentation amount
# - Multi-document structure (sometimes)
# - Tag prefixes and %TAG directives
# Tools that preserve style:
# - ruamel.yaml (Python): round-trip mode preserves comments/order
# - yaml.v3 (Go): preserves key order
# - prettier with yaml plugin: normalizes formatting
# For config files where humans edit:
# - Use ruamel.yaml round-trip mode
# - Or accept that dumps are "normalized"
# - Never overwrite human-edited files with dumper output
# without diffing carefullyEsquemas YAML
Esquema Failsafe
El esquema Failsafe es el más conservador: solo reconoce str, map y seq. Cada escalar es una cadena salvo etiqueta explícita. Útil para entrada no confiable (sin sorpresas de conversión implícita) o como base para esquemas personalizados. La mayoría de cargadores de producción usan un esquema algo más rico.
# Failsafe schema — the most conservative
# Recognizes ONLY three types: str, map, seq
# Everything else is a string
# Under Failsafe:
value: 42 # str "42" (NOT int)
flag: true # str "true" (NOT bool)
empty: null # str "null" (NOT null)
date: 2024-01-01 # str "2024-01-01" (NOT date)
# Use explicit tags to get other types
int_value: !!int 42
bool_value: !!bool true
null_value: !!null null
# When to use Failsafe:
# - Untrusted input (no implicit type coercion)
# - When you want strings only
# - As a base for custom schemas
# PyYAML: SafeLoader uses a schema close to Failsafe
# but with int/float/bool/null inference.Esquema JSON
El esquema JSON coincide exactamente con el sistema de tipos de JSON: str, int, float, bool, null, map, seq. Es más estricto que el esquema Core: sin literales octales/binarios, sin separadores de guion bajo, solo true/false como booleanos, sin inferencia de fechas. Úsalo para interoperar con JSON o para comportamiento de tipos estricto.
# JSON schema — same type system as JSON
# Recognizes: str, int, float, bool, null, map, seq
# Under JSON schema:
int: 42 # int
float: 3.14 # float
str: hello # str
bool: true # bool
null_val: null # null
list: [1, 2, 3] # seq
map: {a: 1} # map
# Differences from Core schema:
# - Stricter number parsing (no 0o octal, no _ separators)
# - Booleans are only true/false (no yes/no)
# - No date/timestamp inference
# When to use JSON schema:
# - Interop with JSON tools
# - Strict type behavior
# - When you want JSON's type semanticsEsquema Core
El esquema Core es el predeterminado de YAML 1.2. Extiende JSON con parseo laxo: hex (0x), octal (0o), binario (0b), guiones bajos en números, flotantes .inf/.nan. Los booleanos son solo true/false (no yes/no). Las fechas son cadenas (sin inferencia). La mayoría de analizadores modernos usan Core por defecto o una variante compatible con 1.1.
# Core schema — the DEFAULT for YAML 1.2
# Extends JSON schema with more lenient scalar resolution
# Under Core schema:
int: 42 # int
neg: -17 # int
hex: 0xFF # int (255)
oct: 0o17 # int (15) [YAML 1.2 syntax]
bin: 0b1010 # int (10)
float: 3.14 # float
exp: 1.0e+3 # float
inf: .inf # float
nan: .nan # float
bool: true # bool (only true/false, not yes/no)
null: null # null (also ~, empty)
str: hello # str
date: 2024-01-01 # str (Core does NOT infer dates)
# Differences from YAML 1.1:
# - yes/no/on/off are STRINGS (not booleans)
# - 017 is a string (octal is 0o17 in 1.2)
# - Dates are strings (no implicit inference)
# Most modern parsers default to Core or close to it.YAML 1.1 frente a 1.2
YAML 1.1 (por defecto en PyYAML) trata yes/no/on/off como booleanos y los números con 0 inicial como octal: fuentes famosas de errores (el 'no' de Noruega → false). YAML 1.2 (la especificación actual) restringe los booleanos a true/false y usa 0o para octal. Comprueba siempre el valor por defecto de tu analizador y entrecomilla las cadenas ambiguas.
# YAML 1.1 (older, used by PyYAML by default)
bool_1_1: yes # true (yes/no/on/off are booleans)
octal_1_1: 017 # 15 (leading 0 = octal)
sexagesimal: 1:30 # 90 (base-60!) - obscure feature
# YAML 1.2 (current spec)
bool_1_2: yes # str "yes" (only true/false are bool)
octal_1_2: 0o17 # 15 (explicit 0o prefix)
no_sexagesimal: 1:30 # str "1:30"
# Practical impact:
# - "no" (Norway) becomes False in PyYAML (1.1)
# - "010" becomes 8 in PyYAML, "010" in 1.2
# - "on"/"off" become True/False in 1.1, strings in 1.2
# PyYAML: defaults to 1.1 behavior
# ruamel.yaml: defaults to 1.2 (with 1.1 compatibility options)
# js-yaml: defaults to 1.1 with 1.2 options
# Go yaml.v3: defaults to 1.2-ish
# Always check your parser's default schema!Diferencias de resolución de tipos
La resolución de tipos difiere entre analizadores YAML 1.1 y 1.2: yes/no/on/off, números con cero inicial y literales sexagesimales se parsean de forma distinta. Mitígalo entrecomillando cadenas ambiguas, fijando la versión con %YAML, usando etiquetas explícitas y probando contra cada analizador objetivo.
# Same YAML, different parsers, different types:
value: yes
# PyYAML (1.1): True (bool)
# js-yaml (1.1): true (bool)
# ruamel (1.2): "yes" (str)
# Go yaml.v3 (1.2): "yes" (str)
# Strict 1.2: "yes" (str)
value: 010
# PyYAML (1.1): 8 (int, octal)
# ruamel (1.2): "010" (str)
# Go yaml.v3 (1.2): "010" (str)
value: 1.0
# All: 1.0 (float) - consistent
value: true
# All: true (bool) - consistent
# Mitigation strategies:
# 1. Quote strings that look like other types
# 2. Pin the YAML version with %YAML 1.2
# 3. Use explicit tags (!!) for critical values
# 4. Test against all target parsersElegir un esquema
Elige el esquema según el caso de uso: 1.2 Core para proyectos nuevos (predecible), 1.1 para interoperar con PyYAML (o entrecomilla las cadenas ambiguas), Failsafe/JSON para entrada no confiable, esquema JSON para interoperar con JSON. Para archivos de configuración, 1.2 Core más entrecomillar cadenas ambiguas ("no", "010", etc.) es la combinación más segura.
# Recommendations for choosing a schema:
# 1. For NEW projects: use YAML 1.2 Core schema
# - More predictable (no yes/no surprises)
# - Modern parsers support it
# - ruamel.yaml, Go yaml.v3 default to it
# 2. For INTEROP with existing PyYAML code:
# - Either accept 1.1 semantics
# - Or use ruamel.yaml with 1.2 + preserve 1.1 features
# - Quote all ambiguous strings explicitly
# 3. For UNTRUSTED input: use Failsafe or JSON schema
# - No implicit type coercion
# - Smaller attack surface
# - Predictable behavior
# 4. For CONFIG FILES: use 1.2 Core + quote ambiguous strings
# - "no", "yes", "on", "off", "010", "1.0" should be quoted
# - Document your schema choice
# - Lint with yamllint
# 5. For JSON INTEROP: use JSON schema
# - Same types as JSON
# - Round-trips cleanlyLint y validación de YAML
yamllint
yamllint es el linter estándar de YAML (Python). Detecta errores de sintaxis, problemas de indentación, espacios finales, marcadores de documento ausentes y más. Úsalo en CI y hooks de pre-commit para detectar problemas de YAML pronto. El modo estricto (-s) trata las advertencias como errores.
# yamllint is the standard YAML linter
# Install: pip install yamllint
# Lint a file
# yamllint config.yaml
# Lint with strict mode (warnings = errors)
# yamllint -s config.yaml
# Output example:
# config.yaml
# 3:4 error mapping values are not allowed here
# 5:1 error syntax error: found character ' ' that cannot start any token
# 8:3 warning missing document start "---"
# 12:5 warning comment is not indented like content
# Lint multiple files
# yamllint file1.yaml file2.yaml file3.yaml
# Lint a directory (recursive)
# yamllint -d path/to/dir
# Read from stdin
# cat config.yaml | yamllint -Configuración del lint
Configura yamllint con .yamllint.yml. Extiende un perfil (default o strict) y luego sobrescribe reglas individuales: indentación, longitud de línea, estilo de comillas, comentarios, espacios finales, marcadores de documento. Ajústalo al estilo de tu equipo. Ejecútalo en CI para aplicarlo de forma consistente.
# .yamllint.yml — configuration file for yamllint
# Place in project root or ~/.config/yamllint/config
# Use a built-in profile
extends: default
# Or use a stricter profile
# extends: strict
# Override specific rules
rules:
# Require document start marker
document-start: disable
# Enforce 2-space indentation
indentation:
spaces: 2
indent-sequences: true
# Max line length
line-length:
max: 120
allow-non-breakable-words: true
# Disallow trailing spaces
trailing-spaces: enable
# Require consistent quoting
quoted-strings:
quote-type: double
required: only-when-needed
# Disallow comments without space before #
comments:
require-starting-space: true
min-spaces-from-content: 1Errores de sintaxis comunes
Errores YAML comunes: tabuladores para indentar (solo se permiten espacios), dos puntos sin espacio después, cadenas sin comillas que contienen dos puntos (se parsean como mapeos), comas finales en estilo flow, indentación inconsistente y claves duplicadas. Un linter detecta cada uno de estos errores automáticamente.
# Error: tab characters for indentation
# bad:
# key: value <- tab not allowed
# Fix: use spaces only
# Error: colon without space
# bad: key:value
# good: key: value
# Error: unquoted special characters
# bad: url: http://example.com:8080 <- parsed as mapping
# good: url: "http://example.com:8080"
# Error: trailing comma in flow
# bad: list: [1, 2, 3,]
# good: list: [1, 2, 3]
# Error: inconsistent indentation
# bad:
# key1: value
# key2: value <- one extra space
# good:
# key1: value
# key2: value
# Error: duplicate keys (some parsers warn)
# bad:
# key: first
# key: second
# good: rename oneErrores de tabulador frente a espacio
Los tabuladores están terminantemente prohibidos para la indentación estructural de YAML: son la causa número 1 de errores de parseo. Los tabuladores dentro de valores de cadena (escalares de bloque, cadenas entrecomilladas) están bien. Configura tu editor para usar espacios (expandtab) en archivos YAML. Detecta las líneas ofensivas con grep -P '\t'.
# YAML FORBIDS tabs for indentation.
# This is the #1 cause of YAML parse errors.
# Symptom: parser error like
# "found character '\t' that cannot start any token"
# or "while scanning for the next token, found tab"
# Tabs are allowed INSIDE string values:
script: |
#!/bin/bash
if [ -f file ]; then # this is fine (literal content)
\techo found # \t inside block scalar is OK
# But tabs for STRUCTURAL indentation are forbidden:
# bad:
# services:
# \tweb:
# \t\timage: nginx
# Fix: convert tabs to spaces
# Configure your editor to use spaces for YAML files
# VS Code: "editor.insertSpaces": true, "editor.tabSize": 2
# Vim: set expandtab shiftwidth=2
# Detect tabs:
# grep -P '\t' file.yaml (finds offending lines)Detección de claves duplicadas
Las claves duplicadas en un mapeo están desaconsejadas y son una fuente común de errores (sobrescritura silenciosa donde gana la última). yamllint las detecta con la regla key-duplicates (activada por defecto). Causas comunes: errores de copiar-pegar y mala resolución de conflictos de fusión. Haz lint siempre en CI para detectarlas pronto.
# Duplicate keys are technically discouraged
# but YAML 1.2 doesn't strictly forbid them.
# Behavior varies by parser (usually last-wins).
config:
host: localhost
port: 8080
host: prod.example.com # silent override!
# yamllint catches these:
# 4:3 error duplication of key "host" in mapping
# Enable in .yamllint.yml:
# rules:
# key-duplicates: enable
# Other tools that detect duplicates:
# - kubeval (for Kubernetes YAML)
# - yq (programmatic checks)
# - Custom schema validation (JSON Schema)
# Common cause: copy-paste errors, merge conflicts
# resolved incorrectly. Always lint in CI to catch.Validación de esquemas
Valida la estructura YAML con JSON Schema (funciona porque YAML es un superconjunto de JSON). Para Kubernetes usa kubeval o kubectl --dry-run. Para configuración general, usa yamllint (sintaxis/estilo) más jsonschema (estructura) o Cue (lenguaje de esquemas). Conecta la validación a hooks de pre-commit y CI.
# Validate YAML against a JSON Schema
# (JSON Schema works on YAML since YAML is a JSON superset)
# Python example with jsonschema + PyYAML:
# import json, yaml, jsonschema
# with open('schema.json') as f: schema = json.load(f)
# with open('config.yaml') as f: doc = yaml.safe_load(f)
# jsonschema.validate(doc, schema)
# Tools for Kubernetes YAML:
# kubeval - validate against K8s schemas
# kubectl apply --dry-run=client -f file.yaml
# conftest - policy-based validation (OPA)
# Tools for general YAML:
# yamllint - syntax + style
# jsonschema-cli - JSON Schema validation
# cue - schema + validation language
# dataladen - config validation
# Pre-commit hook example (.pre-commit-config.yaml):
# repos:
# - repo: https://github.com/adrienverge/yamllint
# rev: v1.32.0
# hooks:
# - id: yamllint
# args: [-s]YAML de Docker Compose
Definición de servicios
Los archivos de Docker Compose definen aplicaciones multicontenedor. Las claves de primer nivel son version, services, volumes, networks, configs y secrets. Cada servicio define image/build, ports, volumes, environment, depends_on y la política de restart. Los volúmenes declarados en el primer nivel tienen nombre y persisten.
# docker-compose.yml — multi-container apps
version: "3.9" # compose file format version
services:
web:
image: nginx:1.25
ports:
- "80:80"
- "443:443"
volumes:
- ./html:/usr/share/nginx/html:ro
restart: unless-stopped
depends_on:
- api
api:
build:
context: ./api
dockerfile: Dockerfile
environment:
- NODE_ENV=production
- DB_URL=postgres://db:5432/app
ports:
- "8080:8080"
restart: always
db:
image: postgres:16
environment:
POSTGRES_PASSWORD: secret
volumes:
- db_data:/var/lib/postgresql/data
restart: always
volumes:
db_data:Volúmenes y redes
Los volúmenes de Compose son bind mounts (host:container), con nombre (declarados en volumes de primer nivel) o anónimos. El sufijo :ro monta en solo lectura. Las redes aíslan servicios; internal: true bloquea el acceso externo. Los volúmenes con nombre persisten los datos entre recreaciones del contenedor.
services:
web:
image: nginx
volumes:
# Bind mount: host:container
- ./html:/usr/share/nginx/html:ro
# Named volume: name:container
- shared_data:/data
# Anonymous volume
- /tmp/cache
networks:
- frontend
- backend
db:
image: postgres
volumes:
- db_data:/var/lib/postgresql/data
networks:
- backend
volumes:
db_data:
driver: local
shared_data:
driver: nfs
driver_opts:
type: nfs
device: ":/path/to/share"
networks:
frontend:
driver: bridge
backend:
driver: bridge
internal: true # no external accessVariables de entorno
Compose soporta tres estilos de variables de entorno: lista (KEY=value), mapa (KEY: value) y env_file. ${VAR} se interpola desde la shell del host o el archivo .env en el momento del parseo; ${VAR:-default} da valores por defecto. Usa $$ para escapar un $ literal. El archivo .env en la raíz del proyecto se carga automáticamente.
services:
api:
image: myapi
# Method 1: list of KEY=value
environment:
- NODE_ENV=production
- LOG_LEVEL=info
# Method 2: map (cleaner)
environment:
NODE_ENV: production
LOG_LEVEL: info
# Method 3: file
env_file:
- .env
- .env.production
# Interpolation from host environment
environment:
- API_KEY=${API_KEY} # from shell
- PORT=${PORT:-8080} # default 8080
# .env file (auto-loaded by docker compose):
# API_KEY=abc123
# PORT=8080
# DB_URL=postgres://...
# Compose substitutes ${VAR} from host shell or .env
# Use $$ to escape (literal $):
# - TOKEN=price_$$5 # produces price_$5Dependencias, healthchecks y restart
depends_on con condition: service_healthy espera a que el healthcheck de la dependencia pase antes de arrancar. Los healthchecks usan test (CMD o CMD-SHELL), interval, timeout, retries y start_period. Políticas de restart: no, always, unless-stopped (sobrevive a reinicios pero respeta la parada manual) y on-failure.
services:
api:
image: myapi
depends_on:
db:
condition: service_healthy # wait for db healthy
redis:
condition: service_started
restart: unless-stopped
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
interval: 30s
timeout: 5s
retries: 3
start_period: 10s
db:
image: postgres
restart: always
healthcheck:
test: ["CMD-SHELL", "pg_isready -U postgres"]
interval: 10s
timeout: 5s
retries: 5
# restart policies:
# no - never restart (default)
# always - always restart on stop
# unless-stopped - restart unless manually stopped
# on-failure - restart only on non-zero exitArchivos de override
Compose fusiona los archivos de override sobre la base. docker-compose.override.yml se aplica automáticamente. Los mapeos se fusionan en profundidad (ganan los overrides); las secuencias normalmente se reemplazan (no se añaden): cuidado con ports/volumes. Usa las banderas -f para fijar el orden explícito de archivos en configuraciones por entorno.
# docker-compose.yml — base
services:
web:
image: nginx
ports:
- "80:80"
environment:
- ENV=base
# docker-compose.override.yml — auto-applied on top
# (loaded automatically by 'docker compose up')
services:
web:
ports:
- "8080:80" # overrides "80:80"
environment:
- DEBUG=true # added
- ENV=override # overrides ENV=base
volumes:
- ./dev.conf:/etc/nginx/conf.d/default.conf
# Multiple override files (-f flag):
# docker compose -f compose.yml -f compose.prod.yml -f compose.secrets.yml up
# Merge rules:
# - mappings: deep-merged (overrides win, others kept)
# - sequences: usually REPLACED (not appended) —
# ports/depends_on/volumes are exceptions in some versions
# Use -f to specify explicit file orderPerfiles y características de Compose
Los perfiles permiten activar servicios opcionalmente (por ejemplo debug, test, ci) con la bandera --profile. Otras características de v3: init (manejo correcto de señales del PID 1), extends (heredar de otro servicio), configs y secrets (montados como archivos) y deploy (ubicación/réplicas/recursos de Swarm). Los perfiles son geniales para mantener un solo compose file para varios entornos.
# Profiles — opt-in services
services:
web:
image: nginx
# no profile: always started
debug:
image: busybox
profiles: ["debug"] # only with --profile debug
loadtest:
image: locust
profiles: ["test", "ci"]
# Enable a profile:
# docker compose --profile debug up
# docker compose --profile test --profile ci up
# Compose file format features (v3.9+):
# - deploy: placement, replicas, resources (Swarm-only in v3)
# - configs: external config files
# - secrets: mounted secret files
# - extends: inherit from another service
# - init: run tini as PID 1
services:
worker:
image: worker
init: true # proper signal handling
extends:
service: base # inherit fields
configs:
- config1
secrets:
- api_key
configs:
config1:
file: ./config.toml
secrets:
api_key:
file: ./api_key.txtYAML de Kubernetes
Estructura de objetos
Cada objeto de Kubernetes tiene apiVersion, kind, metadata y spec. apiVersion es grupo/versión (por ejemplo apps/v1, o v1 para el núcleo). metadata incluye name, namespace, labels y annotations. spec es el estado deseado: Kubernetes trabaja para que la realidad coincida con spec. status lo establece el sistema.
# Every Kubernetes object has the same 4 top-level fields
apiVersion: apps/v1 # API group + version
kind: Deployment # object type
metadata: # identity
name: my-app
namespace: production
labels:
app: my-app
tier: backend
annotations:
deployment.kubernetes.io/revision: "1"
spec: # desired state
replicas: 3
selector:
matchLabels:
app: my-app
template:
metadata:
labels:
app: my-app
spec:
containers:
- name: app
image: my-app:1.0.0
ports:
- containerPort: 8080
# apiVersion + kind + metadata + spec is the universal shape
# (some objects use status too, but you don't set it)Labels y selectors
Las labels identifican y agrupan objetos; los selectors consultan por labels. Se soportan selectores de igualdad (key=value) y de conjunto (In, NotIn, Exists, DoesNotExist). Las annotations guardan metadatos no identificativos (descripciones, contacto, configuración de herramientas). Las labels son para selección; las annotations, para información adicional.
# Labels — identify and group objects
metadata:
labels:
app: my-app
tier: backend
env: production
version: "1.0"
# Selectors — query objects by labels
# Equality-based
selector:
matchLabels:
app: my-app
env: production
# Set-based
selector:
matchExpressions:
- {key: tier, operator: In, values: [backend, api]}
- {key: env, operator: NotIn, values: [dev]}
- {key: version, operator: Exists}
# kubectl commands:
# kubectl get pods -l app=my-app
# kubectl get pods -l 'tier in (backend,api),env!=dev'
# kubectl get pods -l app=my-app -l env=production
# Annotations — non-identifying metadata
metadata:
annotations:
description: "My app deployment"
contact: "[email protected]"Spec de Pod
El spec de un Pod define containers, sus imágenes, puertos, variables de entorno (literales o de secrets/configmaps), recursos (requests/limits), probes (readiness/liveness), volumes y volumeMounts. Los Pods son la unidad desplegable más pequeña, pero normalmente se crean mediante Deployments, no directamente.
apiVersion: v1
kind: Pod
metadata:
name: my-pod
spec:
containers:
- name: app
image: my-app:1.0
ports:
- containerPort: 8080
name: http
env:
- name: LOG_LEVEL
value: info
- name: SECRET_KEY
valueFrom:
secretKeyRef:
name: app-secrets
key: secret-key
resources:
requests: {cpu: 100m, memory: 128Mi}
limits: {cpu: 500m, memory: 512Mi}
readinessProbe:
httpGet: {path: /health, port: 8080}
initialDelaySeconds: 5
periodSeconds: 10
volumeMounts:
- name: config
mountPath: /etc/config
volumes:
- name: config
configMap:
name: app-config
restartPolicy: AlwaysDeployment
Un Deployment gestiona ReplicaSets y Pods. spec.replicas fija el número deseado. strategy.type puede ser RollingUpdate (por defecto, controlado por maxSurge/maxUnavailable) o Recreate. La plantilla de pod (spec.template) define cómo se crean los pods. Gestiona los rollouts con kubectl rollout status/undo/history.
apiVersion: apps/v1
kind: Deployment
metadata:
name: my-app
spec:
replicas: 3
strategy:
type: RollingUpdate
rollingUpdate:
maxSurge: 1
maxUnavailable: 0
selector:
matchLabels:
app: my-app
template:
metadata:
labels:
app: my-app
spec:
containers:
- name: app
image: my-app:1.0.0
ports:
- containerPort: 8080
resources:
requests: {cpu: 100m, memory: 128Mi}
limits: {cpu: 500m, memory: 512Mi}
readinessProbe:
httpGet: {path: /ready, port: 8080}
# Rollback / history
# kubectl rollout status deployment/my-app
# kubectl rollout undo deployment/my-app
# kubectl rollout history deployment/my-appService
Un Service expone Pods como servicio de red. El tipo ClusterIP (por defecto) es solo interno; NodePort expone en cada nodo; LoadBalancer provisiona un LB en la nube; ExternalName es un CNAME de DNS. selector dirige el tráfico a los pods que coinciden. ports mapea el puerto del servicio al targetPort del contenedor (número o nombre).
apiVersion: v1
kind: Service
metadata:
name: my-app
spec:
type: ClusterIP # ClusterIP (default), NodePort, LoadBalancer, ExternalName
selector:
app: my-app # routes to pods with these labels
ports:
- name: http
port: 80 # service port
targetPort: 8080 # container port (or named port)
protocol: TCP
- name: https
port: 443
targetPort: 8443
# NodePort: exposes on each node's IP at a static port (30000-32767)
# LoadBalancer: provisions a cloud LB
# ExternalName: CNAME to an external service
# Service types:
# ClusterIP - internal cluster IP (default)
# NodePort - exposes on node port + ClusterIP
# LoadBalancer - cloud LB + NodePort + ClusterIP
# ExternalName - DNS CNAME (no proxying)ConfigMap y Secret
Los ConfigMaps guardan configuración no sensible (cadenas o archivos); los Secrets, datos sensibles (codificados en base64 en data, o en claro en stringData). Ambos se consumen vía variables de entorno (valueFrom) o montados como volúmenes. Los Secrets NO están cifrados por defecto: activa el cifrado en reposo y restringe el acceso con RBAC.
# ConfigMap — non-sensitive configuration
apiVersion: v1
kind: ConfigMap
metadata:
name: app-config
data:
log_level: info
max_connections: "100"
config.yaml: |
server:
host: 0.0.0.0
port: 8080
---
# Secret — sensitive data (base64-encoded)
apiVersion: v1
kind: Secret
metadata:
name: app-secrets
type: Opaque
data:
# base64-encoded values
api_key: c2VjcmV0LWtleS0xMjM= # echo -n 'secret-key-123' | base64
db_password: cGFzc3dvcmQ=
# Or use stringData for plain text (auto-encoded):
# stringData:
# api_key: secret-key-123
# Consumed by pods:
# env:
# - name: API_KEY
# valueFrom:
# secretKeyRef:
# name: app-secrets
# key: api_key
# volumes:
# - name: config
# configMap:
# name: app-configConfiguración CI/CD (GitHub Actions y GitLab CI)
Workflow de GitHub Actions
Los workflows de GitHub Actions viven en .github/workflows/. on: define los disparadores (push, PR, schedule, workflow_dispatch). jobs contienen runs-on + steps. uses: referencia actions y run: ejecuta shell. Las expresiones usan la sintaxis ${{ }}: deben escaparse como \${{ }} dentro de literales de plantilla YAML.
# .github/workflows/ci.yml
name: CI
on:
push:
branches: [main, develop]
pull_request:
branches: [main]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '20'
- run: npm ci
- run: npm test
- run: npm run build
env:
NODE_ENV: production
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '20'
- run: npm ci
- run: npm run lint
# ${{ }} is GitHub Actions expression syntax
# MUST be escaped as ${{ }} in YAML template literals
# (here we use literal text, no escaping needed)Pipeline de GitLab CI
GitLab CI vive en .gitlab-ci.yml. stages define el orden del pipeline. Los jobs tienen stage, image, script y muchas opciones (only/except, rules, when, artifacts, environment). Las variables usan la sintaxis $VAR (sin escapes necesarios en escalares de bloque YAML). when: manual requiere un clic para desplegar.
# .gitlab-ci.yml
stages:
- test
- build
- deploy
variables:
NODE_ENV: production
IMAGE_TAG: $CI_COMMIT_SHORT_SHA
test:
stage: test
image: node:20
script:
- npm ci
- npm test
artifacts:
reports:
junit: test-results.xml
coverage: '/Lines.*:\s(\d+\.\d+)\%/'
build:
stage: build
image: docker:24
services:
- docker:24-dind
script:
- docker build -t myapp:$IMAGE_TAG .
- docker push myapp:$IMAGE_TAG
only:
- main
deploy:production:
stage: deploy
script:
- ./deploy.sh
environment:
name: production
only:
- main
when: manual # require manual triggerBuilds matriciales
Los builds matriciales ejecutan un job varias veces con variables distintas. GitHub Actions usa strategy.matrix con include/exclude. GitLab usa parallel.matrix. fail-fast: false evita que un fallo cancele a los hermanos. Útil para pruebas multiplataforma y multiversión. La sintaxis ${{ }} debe escaparse en literales YAML.
# GitHub Actions matrix
jobs:
test:
runs-on: ${{ matrix.os }}
strategy:
fail-fast: false
matrix:
os: [ubuntu-latest, macos-latest, windows-latest]
node: [18, 20, 22]
exclude:
- os: windows-latest
node: 18
include:
- os: ubuntu-latest
node: 20
experimental: true
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: ${{ matrix.node }}
- run: npm ci
- run: npm test
# GitLab CI matrix (parallel matrix):
# test:
# image: node:${NODE_VERSION}
# parallel:
# matrix:
# - NODE_VERSION: [18, 20, 22]
# OS: [linux, macos]Workflows reutilizables e includes
Ambos sistemas soportan reutilización. GitHub Actions usa reusable workflows (disparador workflow_call) invocados con uses:. GitLab usa include (project, local, template, remote). La reutilización reduce la duplicación en la lógica de CI compartida. Pasa inputs/secrets explícitamente para mantener los workflows componibles y auditables.
# GitHub Actions: reusable workflow
# .github/workflows/reusable.yml
on:
workflow_call:
inputs:
node-version:
required: true
type: string
secrets:
token:
required: true
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: ${{ inputs.node-version }}
- run: npm ci
env:
TOKEN: ${{ secrets.token }}
# Caller:
# jobs:
# build:
# uses: ./.github/workflows/reusable.yml
# with:
# node-version: '20'
# secrets:
# token: ${{ secrets.MY_TOKEN }}
# GitLab CI: include
# include:
# - project: 'ci/templates'
# file: '/node.yml'
# - local: '/.gitlab/extra.yml'
# - template: Jobs/SAST.gitlab-ci.ymlAnclas en configuraciones de CI
Las anclas YAML reducen la duplicación en configuraciones de CI. GitLab CI las usa intensivamente: define un job oculto (.template) con &anchor y luego <<: *anchor para fusionar. GitHub Actions soporta anclas pero las desaconseja entre jobs (prefiere reusable workflows). Las anclas hacen las configuraciones DRY pero más difíciles de rastrear: úsalas con juicio.
# YAML anchors reduce duplication in CI configs
# GitLab CI commonly uses anchors
.default_template: &default_template
image: node:20
before_script:
- npm ci
cache:
paths:
- node_modules/
test:
<<: *default_template
script:
- npm test
lint:
<<: *default_template
script:
- npm run lint
build:
<<: *default_template
script:
- npm run build
artifacts:
paths:
- dist/
# GitHub Actions supports anchors too (since 2022):
# jobs:
# base: &base
# runs-on: ubuntu-latest
# steps:
# - uses: actions/checkout@v4
# test:
# uses: ./.github/workflows/reusable.yml
# # Anchors across jobs are limited — prefer reusable workflowsEnvironments y secrets
Los environments de GitHub Actions controlan los despliegues (exigen aprobación, restringen ramas) y guardan secrets con ámbito de entorno. Los secrets se referencian vía ${{ secrets.NAME }}. GitLab usa variables protected (restringidas a ramas) y masked (ocultas en logs) definidas en la UI. Nunca registres secrets en logs: pueden filtrarse en la salida de errores.
# GitHub Actions: environments & secrets
jobs:
deploy:
runs-on: ubuntu-latest
environment:
name: production # requires approval if configured
url: https://app.example.com
steps:
- uses: actions/checkout@v4
- name: Deploy
run: ./deploy.sh
env:
DEPLOY_KEY: ${{ secrets.DEPLOY_KEY }}
API_TOKEN: ${{ secrets.API_TOKEN }}
ENV: production
# Secret scopes:
# - Repository secrets: available to all workflows
# - Environment secrets: only when job uses that environment
# - Organization secrets: shared across repos
# GitLab CI: protected/masked variables
# variables:
# # defined in UI: Settings > CI/CD > Variables
# # - Protected: only on protected branches/tags
# # - Masked: hidden in job logs
# deploy:
# script:
# - ./deploy.sh
# environment:
# name: production
# only:
# - mainConsideraciones de seguridad
Riesgos de deserialización
La deserialización YAML es peligrosa porque etiquetas como !!python/object/apply pueden invocar funciones arbitrarias. El yaml.load() de PyYAML era inseguro por defecto antes de 5.1 (ejecución de código con entrada no confiable). Usa siempre yaml.safe_load() para entrada no confiable: rechaza las etiquetas de instanciación de objetos. Otros lenguajes tienen peligros similares (SnakeYAML, Psych).
# YAML deserialization can be DANGEROUS.
# Some loaders let YAML instantiate arbitrary objects.
# DANGEROUS (PyYAML < 5.1, default was unsafe):
# data = yaml.load(untrusted_input)
# An attacker can craft YAML that runs arbitrary code:
# !!python/object/apply:os.system ["rm -rf /"]
# Other dangerous tags:
# !!python/object/apply:... # call any Python function
# !!python/object/new:... # instantiate any class
# !ruby/object:... # Ruby object instantiation
# !java/object:... # Java (SnakeYAML)
# Safe loaders reject these tags by default.
# Modern PyYAML (>= 5.1): yaml.load() requires a SafeLoader
# yaml.safe_load() is ALWAYS safe.
# Rule of thumb:
# - NEVER use yaml.load() on untrusted input
# - ALWAYS use yaml.safe_load() (or full_load on trusted files)
# - Or use a schema-validated loadersafe_load frente a load
Usa siempre safe_load (Python), safe_load (Ruby Psych) o los esquemas seguros por defecto (js-yaml, Go yaml.v3). PyYAML 5.1+ exige un Loader explícito para yaml.load(). full_load permite etiquetas estándar pero no objetos arbitrarios: úsalo solo con archivos de confianza. Los cargadores seguros rechazan todas las etiquetas de instanciación de objetos.
# Python (PyYAML) — the classic safe/unsafe distinction
# SAFE: safe_load rejects all custom tags
import yaml
data = yaml.safe_load(untrusted_yaml) # ALWAYS use this
# SAFE: load with SafeLoader (explicit)
data = yaml.load(untrusted_yaml, Loader=yaml.SafeLoader)
# FULL (trusted files only): full_load allows standard tags
# but not arbitrary python objects
data = yaml.full_load(trusted_yaml)
# UNSAFE: UnsafeLoader allows !!python/object — DANGEROUS
data = yaml.load(untrusted_yaml, Loader=yaml.UnsafeLoader) # NEVER on untrusted
# PyYAML 5.1+ requires Loader argument for yaml.load()
# (raises error without it) — safety improvement.
# Other languages:
# JS (js-yaml): yaml.load(str) uses DEFAULT_SAFE_SCHEMA
# Go (yaml.v3): no object instantiation (safe by design)
# Ruby (Psych): Psych.safe_load is the safe variant
# Java (SnakeYAML): SafeConstructor for safe loadingExplotación de etiquetas locales
Las etiquetas personalizadas (!include, !env, !file, !exec, !template) pueden explotarse incluso sin !!python/object. Un !include que lee archivos puede engañarse para leer /etc/passwd o .ssh/id_rsa mediante path traversal. Audita cada constructor personalizado: valida rutas contra listas de permitidos, rechaza rutas absolutas y ../, y aísla el cargador en sandbox.
# Even non-builtin tags can be exploited if your loader
# registers constructors that have side effects.
# Example: a "harmless" custom tag
# yaml.add_constructor('!include', include_file)
#
# If !include reads files from disk, an attacker can
# craft YAML to read sensitive files:
# config: !include /etc/passwd
# or:
# config: !include /etc/shadow
# or:
# config: !include ../../../.ssh/id_rsa
# Mitigation:
# 1. Validate the included path against an allowlist
# 2. Restrict !include to a specific directory
# 3. Refuse absolute paths and ../ traversal
# 4. Run the loader in a sandbox
# Other "innocent" tags that can be exploited:
# !env VAR_NAME -> leaks env vars
# !exec "command" -> arbitrary command execution
# !file /path -> file disclosure
# !template <% ... %> -> code injection
# Audit every custom constructor for side effects.Billion Laughs y DoS
El ataque Billion Laughs usa alias anidados para expandir un documento diminuto a gigabytes de memoria (10 alias por nivel, 5 niveles = 10^9 referencias). Mitígalo con límites de profundidad de alias, límites de tamaño total, analizadores en streaming y rechazando el anidamiento excesivo. Vigila también el anidamiento profundo (desbordamiento de pila) y las colecciones planas enormes.
# "Billion Laughs" attack — exponential expansion via aliases
a: &a ["lol","lol","lol","lol","lol","lol","lol","lol","lol","lol"]
b: &b [*a,*a,*a,*a,*a,*a,*a,*a,*a,*a]
c: &c [*b,*b,*b,*b,*b,*b,*b,*b,*b,*b]
d: &d [*c,*c,*c,*c,*c,*c,*c,*c,*c,*c]
e: &e [*d,*d,*d,*d,*d,*d,*d,*d,*d,*d]
# This 5-line document expands to ~10^9 string references
# consuming gigabytes of memory on parse.
# Mitigations:
# 1. Limit alias depth (some parsers do this)
# 2. Limit total parsed size / memory
# 3. Use a streaming parser for untrusted input
# 4. PyYAML has a limit but not all parsers do
# 5. Reject documents with excessive alias nesting
# Other DoS vectors:
# - Very deep nesting (parser stack overflow)
# - Huge flat sequences/mappings (memory)
# - Pathological number formats (regex backtracking)
# - Quadratic blowup via duplicate keys
# For untrusted input: set hard size + depth limits.Validación de entrada
Validación por capas: (1) límite de tamaño, (2) safe_load para rechazar etiquetas peligrosas, (3) comprobación de tipo (espera un dict, no una lista), (4) validación de esquema (JSON Schema, Pydantic, Cue), (5) validación de dominio (reglas de negocio como el rango de puertos). Cada capa atrapa ataques distintos. Nunca confíes en la estructura: valida siempre antes de usar.
# Layered defense for untrusted YAML input:
# 1. Size limit (reject oversized input)
MAX_SIZE = 1024 * 1024 # 1 MB
if len(input_text) > MAX_SIZE:
raise ValueError("input too large")
# 2. Safe parser (rejects dangerous tags)
import yaml
try:
data = yaml.safe_load(input_text)
except yaml.YAMLError as e:
raise ValueError(f"invalid YAML: {e}")
# 3. Type check (expect a mapping, not a list)
if not isinstance(data, dict):
raise ValueError("expected a mapping at top level")
# 4. Schema validation (JSON Schema, Pydantic, etc.)
from pydantic import BaseModel, ValidationError
class Config(BaseModel):
host: str
port: int = 8080
try:
config = Config(**data)
except ValidationError as e:
raise ValueError(f"schema validation failed: {e}")
# 5. Domain validation (business rules)
if config.port < 1 or config.port > 65535:
raise ValueError("port out of range")Librerías recomendadas
Elige librerías seguras por defecto: PyYAML (safe_load), ruamel.yaml, js-yaml (seguro por defecto), Go yaml.v3, Psych.safe_load, SnakeYAML con SafeConstructor, serde_yaml. Evita yaml.load sin un cargador seguro explícito. Fija versiones recientes para recibir parches de seguridad. Audita los constructores personalizados. Lee la documentación de seguridad de la librería.
# Safe-by-default YAML libraries by language:
# Python:
# - PyYAML >= 5.1 (yaml.safe_load)
# - ruamel.yaml (safe by default, round-trip mode)
# AVOID: yaml.load without explicit SafeLoader
# JavaScript/TypeScript:
# - js-yaml (yaml.load uses DEFAULT_SAFE_SCHEMA)
# AVOID: yaml.load with DEFAULT_FULL_SCHEMA on untrusted
# Go:
# - gopkg.in/yaml.v3 (no object instantiation, safe)
# AVOID: yaml.v2 has subtle differences, prefer v3
# Ruby:
# - Psych (Psych.safe_load)
# AVOID: YAML.load (uses unsafe loader in old Ruby)
# Java:
# - SnakeYAML with SafeConstructor
# AVOID: new Yaml() without SafeConstructor on untrusted
# (SnakeYAML had CVEs from unsafe loading)
# Rust:
# - serde_yaml (safe by design, no arbitrary types)
# General rule:
# - Read the library's security docs
# - Pin to a recent version (security patches)
# - Use safe_load / SafeConstructor / safe schema
# - Audit custom constructors for side effectsBuenas prácticas
Indentación consistente
Usa 2 espacios de forma consistente (el estándar de facto), nunca tabuladores. Configura tu editor para insertar espacios en YAML. Usa formateadores (prettier, yamlfixer) y linters (yamllint) para imponer la consistencia. La indentación inconsistente es el error YAML más común y rompe el parseo.
# Use 2 spaces for indentation (most common)
# NEVER use tabs (YAML forbids them)
# GOOD
server:
host: localhost
port: 8080
routes:
- path: /api
handler: apiHandler
- path: /web
handler: webHandler
# BAD (inconsistent)
# server:
# host: localhost
# port: 8080 # wrong indent
# Configure your editor:
# VS Code: "[yaml]": {"editor.insertSpaces": true, "editor.tabSize": 2}
# Vim: autocmd FileType yaml setlocal ts=2 sts=2 sw=2 expandtab
# Emacs: (add-hook 'yaml-mode-hook
# (lambda () (setq yaml-indent-offset 2)))
# Use a formatter:
# prettier (with yaml plugin) normalizes indentation
# yamllint checks it
# yamlfixer auto-fixes issuesEstrategia de comillas
Entrecomilla las cadenas que parezcan números, booleanos, null o fechas; que contengan dos puntos/comas/caracteres especiales; o que empiecen por indicadores (- ? : * & ! | > ' " % @). En los demás casos prefiere plano (sin comillas) por legibilidad. Usa comillas dobles para secuencias de escape (\n, \t) y simples para cadenas literales con apóstrofes.
# Quote strings when:
# 1. They look like another type (number, bool, null, date)
version: "1.0" # string, not float
answer: "yes" # string, not bool (1.1)
region: "no" # string "no", not False (1.1)
date: "2024-01-01" # string, not date
phone: "555-1234" # string, not number
# 2. They contain special characters
url: "https://example.com:8080" # colon
list: "a, b, c" # comma
expr: "value:with:colons" # colons
# 3. They start with special indicators (-, ?, :, *, &, !, |, >, ', ", %, @, `)
flag: "-not-a-list"
key: "?not-a-complex-key"
# Don't quote otherwise — plain is more readable
name: Alice # no quotes needed
path: /usr/local/bin # no quotes needed
# Prefer double quotes for escapes (\n, \t)
# Prefer single quotes for literal strings with apostrophes
greeting: "Hello\nWorld"
possessive: 'Alice''s car'Evitar tabuladores y otros peligros
Evita los peligros comunes: tabuladores (prohibidos: usa espacios), yes/no/on/off sin comillas (ambigüedad 1.1 frente a 1.2), cadenas sin comillas con dos puntos, espacios en blanco finales, finales de línea CRLF (usa LF), BOM (guarda como UTF-8 sin BOM) y líneas muy largas (parte con escalares de bloque). Un linter detecta la mayoría.
# Pitfall 1: tabs for indentation (FORBIDDEN)
# Configure editor to use spaces
# Pitfall 2: yes/no/on/off as strings (1.1 vs 1.2)
# Always quote: "yes", "no", "on", "off"
# Pitfall 3: unquoted strings with colons
# bad: url: http://x:8080
# good: url: "http://x:8080"
# Pitfall 4: trailing whitespace
# Some parsers are strict; linters always flag it
key: value # <- no trailing spaces
# Pitfall 5: Windows line endings (CRLF)
# Use LF (\n) only — CRLF can cause subtle issues
# .gitattributes: *.yaml text eol=lf
# Pitfall 6: BOM at start of file
# Save as UTF-8 without BOM
# Pitfall 7: very long lines
# Wrap with block scalars or flow style
description: >
This is a long description that wraps
across multiple lines for readability.
# Pitfall 8: inconsistent key ordering
# Group related keys, be consistentFijar versión y documentar el esquema
Fija la versión de YAML con %YAML 1.2 si las diferencias entre 1.1 y 1.2 importan. Documenta tu esquema: campos obligatorios/opcionales, tipos, defaults, rangos, en comentarios, un archivo JSON Schema o un README. Fija las versiones del esquema en el código para que la validación de configuración sea reproducible. Esto reduce la fricción de incorporación y los errores de configuración.
# Pin the YAML version if it matters
%YAML 1.2
---
key: value
# Document your schema expectations in comments:
# Required fields:
# - host: string (hostname or IP)
# - port: integer (1-65535)
# Optional fields:
# - tls: boolean (default: false)
# - cert: string (path, required if tls: true)
config:
host: example.com
port: 443
tls: true
cert: /etc/ssl/cert.pem
# Or use a JSON Schema file (config.schema.json)
# and reference it from your docs / CI:
# "Validated against schema v1.2; see config.schema.json"
# For libraries, document the schema in the README:
# ## Configuration
# The config.yaml file must contain:
# - host (str, required)
# - port (int, required, 1-65535)
# - tls (bool, optional, default: false)
# Pin schema versions in code:
# CONFIG_SCHEMA_VERSION = "1.2"
# validate(data, schema_v1_2)Lint en CI
Conecta el lint de YAML a CI (GitHub Actions, GitLab CI) y a hooks de pre-commit. Usa yamllint para sintaxis/estilo y prettier para formateo. La integración en el editor (extensión YAML de VS Code, yaml-language-server) da lint en línea y validación de esquemas. Detectar errores de YAML en CI cuesta mucho menos que en producción.
# .github/workflows/lint.yml
name: Lint YAML
on: [push, pull_request]
jobs:
yamllint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install yamllint
run: pip install yamllint
- name: Lint
run: yamllint -s .
# GitLab CI:
# yamllint:
# image: python:3.12
# script:
# - pip install yamllint
# - yamllint -s .
# Pre-commit hook (.pre-commit-config.yaml):
# repos:
# - repo: https://github.com/adrienverge/yamllint
# rev: v1.35.1
# hooks:
# - id: yamllint
# args: [-s, --config-file, .yamllint.yml]
# - repo: https://github.com/pre-commit/mirrors-prettier
# rev: v3.1.0
# hooks:
# - id: prettier
# types: [yaml]
# Editor integration:
# VS Code: install "YAML" extension (redhat)
# + "yamllint" for inline linting
# + schema validation via yaml-language-serverEstructura y legibilidad
Agrupa las claves relacionadas con encabezados de comentario. Mantén el anidamiento poco profundo (3-4 niveles como máximo): el YAML profundamente anidado es difícil de leer. Usa anclas para valores genuinamente reutilizados. Usa escalares de bloque para cadenas multilínea. Mantén las líneas por debajo de 120 caracteres. La legibilidad importa porque los humanos editan YAML.
# Group related keys; use comments to delineate sections
server:
# Networking
host: 0.0.0.0
port: 8080
tls:
enabled: true
cert: /etc/ssl/cert.pem
# Limits
timeout: 30
max_connections: 100
retries: 3
# Keep nesting shallow (3-4 levels max)
# Deeply nested YAML is hard to read and edit.
# If a value is reused, use an anchor:
defaults: &defaults
timeout: 30
retries: 3
prod:
<<: *defaults
env: production
staging:
<<: *defaults
env: staging
# Use block scalars for multi-line values
script: |
#!/bin/bash
set -e
echo "deploying"
# Keep lines under 120 chars; wrap with block scalars or
# multi-line flow style.Características avanzadas
Claves de mapeo complejas
El indicador ? marca una clave compleja (un mapeo o secuencia usado como clave). Útil para tablas de búsqueda (por ejemplo, precios por región+instancia). Advertencia: muchos serializadores no preservan las claves complejas y pueden convertirlas en cadena al emitir. La mayoría de archivos de configuración se atienen a claves de cadena planas por simplicidad y compatibilidad con herramientas.
# Use ? to mark a complex (non-scalar) key
? apple
: red fruit
? orange
: orange fruit
# A mapping as a key
? host: localhost
port: 8080
: connection_string
# A sequence as a key
? [us-east-1, t2.micro]
: 0.0116
? [us-east-1, t2.small]
: 0.023
? [us-west-2, t2.micro]
: 0.0125
# Useful for lookup tables
pricing:
? [production, large]
: 100
? [production, small]
: 50
? [development, large]
: 20
# In flow style:
{[a, b]: value, {x: 1}: other}
# Caveat: many serializers don't preserve complex keys
# and may convert them to strings on output.Conjuntos (!!set)
Un set de YAML (!!set) es un mapeo donde las claves son los elementos y los valores son null. Algunos analizadores lo mapean a un tipo Set nativo. Úsalo para declarar colecciones únicas (roles, permisos). Advertencia: JSON no tiene tipo Set, así que la conversión a JSON produce un objeto con valores null. Algunos serializadores no preservan la etiqueta !!set.
# A set is a mapping with null values
# Use the !!set tag for clarity
permissions: !!set
? read
? write
? execute
# Equivalent to:
permissions:
read: null
write: null
execute: null
# Or in flow style:
flags: !!set { red, green, blue }
# Parsers may map this to a native Set type:
# Python: set() (PyYAML with !!set constructor)
# Ruby: Set (Psych)
# JavaScript: depends on library
# Use case: declare a unique collection
roles: !!set
? admin
? editor
? viewer
# Caveat: JSON has no Set type, so JSON conversion
# usually produces an object with null values.Mapeos ordenados (!!omap)
!!omap (mapeo ordenado) es una secuencia de mapeos de una sola clave que preserva el orden de inserción. Útil para cronologías, preferencias ordenadas o donde el orden importa semánticamente. Los analizadores modernos preservan igualmente el orden de los mapeos normales (dict de Python 3.7+, Hash de Ruby), pero los mapas de Go son aleatorios: !!omap hace explícito el orden ahí.
# An ordered mapping preserves key order
# Use !!omap tag
timeline: !!omap
- 2024-01-01: event A
- 2024-02-01: event B
- 2024-03-01: event C
# Equivalent representation as a list of single-key mappings:
# timeline:
# - 2024-01-01: event A
# - 2024-02-01: event B
# - 2024-03-01: event C
# Parsers may map this to:
# Python: list of tuples, or OrderedDict
# Ruby: Array of one-key hashes (or OrderedDict)
# Go: ordered map (with custom type)
# Use case: ordered key-value pairs where order matters
# - event timelines
# - ordered preferences
# - step-by-step configurations
# Caveat: regular YAML mappings DO preserve order in
# most modern parsers (Python dict 3.7+, Ruby Hash,
# Go map iteration is random though). !!omap makes the
# intent explicit and works even where maps are unordered.Datos binarios (!!binary)
!!binary codifica datos binarios como base64 en YAML. Los analizadores los decodifican a bytes nativos (bytes de Python, cadena ASCII-8BIT de Ruby). Útil para incrustar imágenes pequeñas o iconos directamente. Para datos binarios grandes, prefiere referenciarlos por ruta o URL. El base64 multilínea funciona con escalares de bloque plegado (>) o literal (|).
# Encode binary data as base64 with !!binary tag
image: !!binary "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9
awAAAABJRU5ErkJggg=="
# Multi-line base64 (folded or literal works)
data: !!binary |
iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42m
k+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==
# Parsers decode to bytes:
# Python: bytes object
# Ruby: ASCII-8BIT string
# JavaScript: depends on library (often base64 string)
# Use case: embed small images, icons, or other binary
# directly in YAML config
# For larger binary data, prefer:
# - Reference by path: image: /path/to/image.png
# - Reference by URL: image: https://example.com/img.png
# - Store separately and link
# Verify with:
# python -c 'import yaml; d=yaml.safe_load(open("f.yaml")); print(len(d["image"]))'Constructores personalizados
Registra constructores personalizados para mapear etiquetas (!money) a objetos nativos. Usa add_constructor con un loader con ámbito SafeLoader. Los constructores reciben el loader y el nodo; usa construct_scalar/mapping/sequence para leer el valor del nodo. Audita siempre los constructores por efectos secundarios (lecturas de archivos, llamadas a subprocesos): pueden explotarse con entrada no confiable.
# PyYAML: register a constructor for a custom tag
import yaml
class Money:
def __init__(self, currency, amount):
self.currency = currency
self.amount = amount
def __repr__(self):
return f"Money({self.currency} {self.amount})"
def money_constructor(loader, node):
value = loader.construct_scalar(node) # "USD 19.99"
currency, amount = value.split()
return Money(currency, float(amount))
# Register the constructor (use SafeLoader scope)
yaml.add_constructor('!money', money_constructor, Loader=yaml.SafeLoader)
# Now this YAML parses to a Money object:
# price: !money "USD 19.99"
config = yaml.safe_load("price: !money \"USD 19.99\"")
print(config['price']) # Money(USD 19.99)
# Multi-argument constructors use construct_mapping or
# construct_sequence depending on the node kind.
# SECURITY: audit every constructor for side effects.
# A constructor that calls open(), os.system(), or
# subprocess can be exploited via untrusted input.Características de YAML 1.2 y futuro
YAML 1.2 hizo de JSON un subconjunto estricto, restringió los booleanos a true/false y adoptó 0o para octal. La merge key << se eliminó de la especificación núcleo pero sigue ampliamente soportada. YAML 1.2.2 (2021) aclaró la especificación; la 1.3 está en desarrollo. Prepara el futuro fijando la versión, entrecomillando cadenas ambiguas y considerando Cue/Dhall/Jsonnet para configuración compleja.
# YAML 1.2 (2009, current spec) key changes from 1.1:
# - JSON is a strict subset
# - Booleans: only true/false (not yes/no/on/off)
# - Octal: 0o prefix (not leading 0)
# - Removed sexagesimal numbers
# - Removed merge key << from core spec (still widely supported)
# YAML 1.3 (in development) aims to:
# - Clarify ambiguous parts of 1.2
# - Standardize error reporting
# - Improve interoperability between parsers
# - Possibly restore some 1.1 features as optional
# YAML 1.2.2 (2021 update, spec revision):
# - Clarified type resolution
# - Better-defined core schema
# - Improved examples
# - No breaking changes
# Recommended practices for future-proofing:
# 1. Pin %YAML 1.2 in critical files
# 2. Quote ambiguous strings (yes/no, leading-zero numbers)
# 3. Avoid relying on << merge key for new formats
# (or document that you depend on it)
# 4. Use JSON-compatible subset when interop matters
# 5. Watch for YAML 1.3 adoption in your parser
# Some tools (Cue, Dhall, Jsonnet) extend/replace YAML
# for complex configuration — consider them for new
# projects with advanced needs.Fragmentos de YAML relacionados
Copy-paste ready code for common tasks.
Scalars
Strings, numbers, booleans, null, and dates.
Sequences and Mappings
Lists and key-value maps.
Anchors and Aliases
Reuse nodes with anchors, aliases, and merge keys.
Multi-Document
Several documents in one stream.
Tags
Explicit type tags for custom resolution.
Flow Style
Inline JSON-like sequences and mappings.
Block Style
Indentation-based nesting.
Schema Types
How YAML 1.1 and 1.2 resolve scalars.
Was this helpful?