jsonyamlconfiguration

JSON vs YAML: ¿Cuándo usar cada formato?

10 de junio de 2026 · Cosyslabs

JSON es la elección correcta para APIs, intercambio de datos y configuración generada por máquinas. YAML es mejor para archivos de configuración escritos por humanos donde los comentarios, la legibilidad y la puntuación mínima son importantes. YAML es un superconjunto de JSON — todo documento JSON válido es YAML válido, pero YAML tiene trampas significativas que debes conocer antes de adoptarlo.

Comparación de sintaxis

// JSON
{
  "servidor": {
    "host": "localhost",
    "puerto": 8080,
    "tls": true
  },
  "baseDeDatos": {
    "url": "postgres://localhost/mibd",
    "pool": {
      "min": 2,
      "max": 10
    }
  },
  "caracteristicas": ["auth", "api", "admin"]
}

# YAML — los mismos datos, más legibles
servidor:
  host: localhost
  puerto: 8080
  tls: true

baseDeDatos:
  url: postgres://localhost/mibd
  pool:
    min: 2
    max: 10

caracteristicas:
  - auth
  - api
  - admin

YAML elimina comillas, llaves, corchetes y comas. Usa sangría (solo espacios — sin tabulaciones) para transmitir la estructura.

YAML es un superconjunto de JSON

Puedes incrustar JSON directamente en un archivo YAML y es válido:

# Esto es YAML válido
nombre: Alice
config: {"debug": true, "nivel": 3}

Esto significa que los analizadores YAML pueden analizar JSON, y los conversores YAML-a-JSON son sin pérdida (excepto para características específicas de YAML como anclas y comentarios, que JSON no puede representar).

Dónde JSON gana

Respuestas de API

JSON es la lengua franca de las APIs REST. Cada cliente HTTP, desde curl hasta el navegador fetch, maneja JSON de forma nativa:

const respuesta = await fetch("/api/usuarios");
const datos = await respuesta.json(); // Análisis JSON integrado

YAML no tiene soporte nativo en el navegador y añade una dependencia de analizador (~15 KB para js-yaml).

Manejo estricto de tipos

JSON tiene tipos explícitos: cadena, número, booleano, null, arreglo, objeto. YAML infiere tipos de los valores, lo que causa errores notorios.

Datos generados por máquinas

Los programas que generan configuración o datos deben emitir JSON. JSON es inequívoco, ampliamente soportado y no depende del espacio en blanco.

Ecosistema JavaScript

package.json, tsconfig.json, eslintrc.json — las herramientas de JavaScript estandarizaron en JSON. Los editores proporcionan validación de JSON Schema con autocompletado y detección de errores.

Dónde YAML gana

Configuración escrita por humanos

# YAML permite comentarios — JSON no
# Este comentario explica por qué el timeout es alto
servidor:
  timeout: 30000  # milisegundos — los clientes heredados necesitan más tiempo

# Las cadenas multilínea son legibles en YAML
mensaje: |
  Bienvenido al sistema.
  Tu cuenta ha sido creada.
  Por favor verifica tu correo electrónico.

Kubernetes, GitHub Actions, Docker Compose

El ecosistema nativo de la nube estandarizó en YAML para manifiestos y pipelines:

# Flujo de trabajo de GitHub Actions
name: CI
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm test

Cadenas multilínea

YAML maneja cadenas multilínea elegantemente con escalares de bloque:

# Escalar de bloque literal — preserva saltos de línea
descripcion: |
  Línea uno.
  Línea dos.
  Línea tres.

# Escalar de bloque plegado — los saltos de línea se convierten en espacios
resumen: >
  Este texto largo será
  plegado en una sola línea
  al ser analizado.

JSON requiere \n escapado:

{
  "descripcion": "Línea uno.\nLínea dos.\nLínea tres."
}

Trampas de YAML (El problema de Noruega y otros)

La inferencia de tipos de YAML ha causado incidentes reales en producción.

El problema de Noruega

paises:
  - GB
  - DE
  - NO   # YAML 1.1 analiza esto como booleano false!
  - SE

En YAML 1.1 (usado por muchos analizadores antiguos), no, NO, No se analizan como false. De manera similar, yes, YES, Yes se convierten en true. YAML 1.2 (2009) elimina este comportamiento, pero muchos analizadores todavía implementan 1.1.

Solución: Poner entre comillas los valores que podrían ser mal interpretados:

paises:
  - "GB"
  - "DE"
  - "NO"   # Ahora de forma segura una cadena
  - "SE"

Análisis de números octales

permisos_archivo: 0777  # YAML 1.1: ¡se analiza como octal 511, no decimal 777!
puerto: 0755             # octal 493

En YAML 1.2, los ceros iniciales no implican octal. En 1.1, sí. Pon entre comillas los valores numéricos donde la precisión importa.

Errores de sangría

YAML usa solo espacios — mezclar tabulaciones y espacios causa errores del analizador:

servidor:
  host: localhost
	puerto: 8080  # TABULACIÓN aquí — ¡error de análisis YAML!

Claves duplicadas

config:
  debug: true
  debug: false  # ¿Cuál gana? Comportamiento indefinido

Diferentes analizadores manejan las claves duplicadas de manera diferente (gana el último, gana el primero, o error).

Conversión

// YAML a JSON (Node.js)
import yaml from "js-yaml";
import fs from "fs";

const contenidoYaml = fs.readFileSync("config.yaml", "utf8");
const analizado = yaml.load(contenidoYaml);
const json = JSON.stringify(analizado, null, 2);

import yaml, json

with open("config.yaml") as f:
    datos = yaml.safe_load(f)  # ¡Usar safe_load, no load!

print(json.dumps(datos, indent=2))

Siempre usa yaml.safe_load() en Python, nunca yaml.load(). La versión insegura puede ejecutar código Python arbitrario mediante deserialización YAML — un conocido vector de RCE.

Guía de decisión

Situación	Elegir
Respuestas de API REST	JSON
gRPC / Protocol Buffers	Ninguno (binario)
`package.json`, `tsconfig.json`	JSON
Manifiestos de Kubernetes	YAML
GitHub Actions / CI	YAML
Docker Compose	YAML
Playbooks de Ansible	YAML
Config donde se necesitan comentarios	YAML
Config generada por máquinas	JSON
Config escrita por humanos	YAML
Datos con muchas cadenas	YAML (sin necesidad de comillas)

Pruébalo ahora

Convierte entre JSON y YAML al instante con la Herramienta Formateador JSON y la Herramienta Formateador YAML — ambas se ejecutan completamente en tu navegador.

Más herramientas de Cosyslabs

PDF Convert All — Convierte, fusiona y comprime PDFs. Muchos pipelines de generación de documentos consumen configuración JSON o YAML.
Unit Convert All — Convierte valores de medidas que suelen encontrarse en archivos de configuración (p. ej., timeouts en ms, tamaños de archivo en MB).
Rough Estimator — Estima el esfuerzo de migrar sistemas de configuración basados en JSON a YAML (o viceversa) en una base de código grande.
Cosyslabs — El estudio detrás de Dev Tools !, Routine Toolkit, y más.

← Back to all articles