Formateador de YAML: formatea, reindenta y valida YAML

YAML es sensible al espacio en blanco, así que un tab perdido o una indentación inconsistente no solo se ve desordenado —— cambia el significado o rompe el parseo. Un formateador de YAML arregla eso: re-indenta tu YAML a una profundidad consistente, normaliza el espaciado, y (opcionalmente) ordena las keys, para que el archivo sea legible y produzca diffs limpios. Esta guía explica qué hace un formateador YAML, las reglas de indentación que aplica, las trampas de tipos que vigilar, y cuándo formatear YAML versus convertirlo a JSON.

Qué hace un formateador de YAML

Un formateador parsea tu YAML en una estructura de datos y lo re-serializa con un estilo consistente. Los datos no cambian —— solo la presentación se normaliza:

• Re-indenta cada nivel a un ancho fijo (comúnmente 2 espacios) y reemplaza tabs por espacios
• Normaliza el espaciado alrededor de los dos puntos, los dashes de las listas y las colecciones inline
• Opcionalmente ordena las keys para un orden canónico amigable con diffs
• Valida como efecto secundario —— si no puede parsear, tienes un error de sintaxis que arreglar primero

# Antes —— indentación mezclada, difícil de leer
server:
    host: api.example.com
    ports:
    - 8080
    - 8443
database: {name: mydb, pool: 5}

# Después —— indent de 2 espacios, normalizado
server:
  host: api.example.com
  ports:
    - 8080
    - 8443
database:
  name: mydb
  pool: 5

Por qué formatear YAML

• Legibilidad —— pipelines de CI, manifiestos de Kubernetes y archivos Docker Compose se anidan profundamente; una indentación consistente los hace escaneables.
• Diffs y reviews limpios —— formato normalizado (y keys ordenadas) significa que un pull request muestra solo cambios reales, no ruido de espacios en blanco.
• Detectar errores temprano —— el formateo solo tiene éxito en YAML válido, así que un formateador funciona también como chequeo rápido de validez.
• Consistencia en el equipo —— un estilo aplicado automáticamente, en lugar de hábitos de indentación por autor.

Las reglas de indentación que aplica un formateador

La mayoría de errores de YAML son errores de indentación, y son exactamente lo que un formateador estandariza:

• Solo espacios —— nunca tabs. YAML prohíbe caracteres tab para indentación. Un solo tab es el bug YAML más común del «¿por qué no parsea esto?».
• Profundidad consistente. Las keys hermanas deben estar indentadas con el mismo número de espacios respecto a su padre. Un formateador reescribe todo a un ancho fijo.
• Alineación de listas. Los items en una secuencia de bloque (-) se alinean bajo su key; un formateador normaliza si el dash está indentado o al ras.

Trampas de tipos al reformatear

El formateo preserva los datos, pero la inferencia de tipos de YAML aún puede sorprenderte cuando los valores no están entre comillas —— vale la pena saberlo antes de confiar en la salida:

• El «Norway problem». Sin comillas, NO, yes, on, off pueden leerse como booleanos, así que el código de país NO se vuelve false. Pon comillas a esos valores para mantenerlos como strings.
• Ceros a la izquierda y números grandes.007 puede perder sus ceros si se lee como número; enteros muy grandes pueden perder precisión. Pon comillas a IDs que deban permanecer como strings.
• Fechas y timestamps. Algunos parsers coercen strings sin comillas que parecen fechas a tipos timestamp. Ponles comillas si necesitas el string literal.

Estilo bloque vs estilo flow

YAML tiene dos formas de escribir colecciones: bloque (indentado, orientado a líneas) y flow (inline, estilo JSON con [] / {}):

# bloque
ports:
  - 80
  - 443

# flow (mismos datos)
ports: [80, 443]

Los formateadores típicamente normalizan al estilo bloque por legibilidad. El estilo flow es compatible con JSON —— útil cuando embeber YAML dentro de herramientas que solo manejan JSON —— pero más difícil de leer a medida que crece la anidación.

Anchors y aliases: fragmentos reutilizables

& marca un anchor; * lo referencia. Útil para compartir config entre servicios sin copia-pega, y los formateadores los preservan:

defaults: &defaults
  retries: 3
  timeout: 30
api:
  <<: *defaults
  url: https://api.example.com
worker:
  <<: *defaults
  url: https://worker.example.com

Nota: los anchors y aliases desaparecen cuando conviertes a JSON —— JSON no tiene tipo de referencia, así que los valores se ponen inline. Un round-trip YAML → JSON → YAML los pierde.

Lint más allá del parseo: yamllint

Un formateador normaliza la forma; yamllint aplica una guía de estilo (longitud de línea, orden de keys, marcadores de inicio de documento, valores truthy, espaciado de comentarios). Combínalos en CI: formatea primero, luego lint con las reglas que elija tu equipo.

Formatear YAML vs convertir a JSON

Formatear mantiene el archivo como YAML —— mejor cuando humanos seguirán editándolo. Convertir a JSON es para cuando un programa necesita consumirlo (la mayoría de apps solo parsean JSON en runtime). Como YAML 1.2 es un superconjunto estricto de JSON, la conversión es sin pérdida para los datos; ve Convertir YAML a JSON y JSON vs YAML para cuándo usar cada uno.

Formatea y valida YAML en tu navegador

Pega tu YAML en el validador y formateador YAML de fixjson y haz clic en Format YAML para re-indentarlo y normalizarlo, o To JSON para convertir. Reporta la línea exacta de cualquier error de sintaxis, y todo corre en tu navegador —— sin subida —— lo cual importa para archivos de configuración que contienen hosts, secretos o ajustes internos.

Preguntas frecuentes

¿Qué hace un formateador YAML?

Parsea tu YAML y lo re-serializa con indentación y espaciado consistentes (y opcionalmente keys ordenadas), para que el archivo sea legible y amigable con diffs. Los datos no cambian —— solo el formato se normaliza.

¿Por qué mi YAML falla al parsear?

Casi siempre indentación: un carácter tab (YAML prohíbe tabs para indentación) o keys hermanas a profundidades inconsistentes. Un formateador reescribe todo a un solo ancho basado en espacios, lo que saca a la luz y arregla la mayoría de estos casos.

¿Formatear YAML cambia mis datos?

No —— solo cambia espacios y orden de keys. Vigila los valores sin comillas: YAML puede inferir tipos (el «Norway problem»), así que pon comillas a valores como NO o 007 que deban quedarse como strings.

¿Debería formatear YAML o convertirlo a JSON?

Formatea cuando humanos sigan editando el archivo; convierte a JSON cuando un programa lo consuma. Muchos equipos escriben YAML y convierten a JSON al cargar.

Herramientas y guías relacionadas

• Validador y formateador YAML —— formatea, valida y convierte YAML en tu navegador
• Convertir YAML a JSON —— la conversión y las trampas de indentación
• JSON vs YAML —— diferencias y cuándo usar cada uno
• Cómo formatear JSON —— el equivalente en JSON