JSON vs YAML: diferencias y casos de uso

JSON y YAML son los dos formatos de serialización textual más utilizados para describir datos estructurados: configuración de aplicaciones, payload de API, archivos de infraestructura, manifiestos de Kubernetes, pipelines CI/CD. Ambos representan las mismas estructuras fundamentales (objetos, listas, escalares) pero con filosofías diferentes: JSON privilegia la legibilidad para máquinas y la universalidad, YAML apuesta por la legibilidad humana y la concisión. Este artículo compara ambos formatos punto por punto para ayudarte a elegir.

¿Qué es JSON?

JSON (JavaScript Object Notation) es un formato de serialización presentado por Douglas Crockford a principios de los años 2000, derivado de la sintaxis literal de objeto de JavaScript. Estandarizado por la RFC 8259 y ECMA-404, es hoy el formato pivote de la web: la práctica totalidad de las API REST, las bases NoSQL y las configuraciones frontend lo utilizan.

JSON se basa en dos estructuras:

• Una colección ordenada de pares clave-valor (el objeto, entre llaves)
• Una lista ordenada de valores (el array, entre corchetes)

Los valores escalares son string, number, true, false o null. Las cadenas están obligatoriamente delimitadas por comillas dobles. JSON no soporta comentarios.

¿Qué es YAML?

YAML (YAML Ain't Markup Language) es un formato aparecido en 2001, diseñado desde el principio para ser legible por un humano. La especificación actual es YAML 1.2.2. Su característica distintiva: utiliza la indentación para expresar la jerarquía, al estilo de Python.

YAML es un superconjunto de JSON desde la versión 1.2: todo documento JSON válido es un documento YAML válido. Pero YAML añade mucho más: comentarios, cadenas sin comillas, multilínea, anclas y alias, tags para el tipado explícito, varios documentos en un mismo archivo (---).

Sintaxis comparada

Aquí tienes la misma estructura expresada en ambos formatos.

JSON

{
  "name": "cdrn",
  "version": "1.14",
  "tags": ["seo", "tools", "open-source"],
  "author": {
    "name": "Adrien",
    "email": "contact@example.com"
  },
  "active": true,
  "stars": null
}

YAML

# Configuration projet
name: cdrn
version: "1.14"
tags:
  - seo
  - tools
  - open-source
author:
  name: Adrien
  email: contact@example.com
active: true
stars: null

Sobre el mismo contenido, YAML ocupa aproximadamente el mismo número de líneas pero evita las llaves, los corchetes, las comas finales y las comillas en la mayoría de las cadenas. Los comentarios (líneas #) están permitidos.

Tipos soportados

JSON conoce 6 tipos: object, array, string, number, boolean, null. Sin fecha nativa, sin binario, sin distinción explícita entre entero y flotante.

YAML 1.2 conoce los mismos que JSON y añade: timestamps ISO 8601, binarios (codificados en base64 mediante el tag !!binary), enteros y floats distintos, infinito, NaN, y los tipos personalizados mediante tags (!!str, !!int, !!float...). YAML 1.1 aceptaba yes/no/on/off como booleanos: una trampa clásica en los parsers antiguos.

Rendimiento y ecosistema

JSON es típicamente de 3 a 10 veces más rápido de parsear que YAML, y sus parsers están disponibles en todas partes (integrados en el runtime de la práctica totalidad de los lenguajes). Las bibliotecas YAML son más pesadas porque gestionan una gramática más rica (anchors, tags, multidocumento).

Por el lado del ecosistema: JSON domina las API HTTP, las bases NoSQL (MongoDB, CouchDB), los archivos package.json, composer.json, tsconfig.json. YAML se ha impuesto para la configuración de aplicaciones y la infraestructura como código: Symfony, Spring Boot, Rails, Docker Compose, Kubernetes, GitHub Actions, GitLab CI, Ansible.

Tabla comparativa

Casos de uso típicos

Elegir JSON cuando

• Diseñas una API REST o un endpoint webhook
• Almacenas datos en una base NoSQL o una caché
• Intercambias datos entre frontend y backend
• El rendimiento de parsing es crítico (alto rendimiento, edge)
• Quieres un formato universalmente soportado sin dependencias

Elegir YAML cuando

• Escribes una configuración de aplicación editada a mano
• Necesitas comentarios para documentar las opciones
• Escribes Kubernetes, Docker Compose, GitHub Actions, Ansible
• Quieres factorizar bloques con anclas y alias
• La legibilidad prima sobre la velocidad de procesamiento

Recomendación

La regla sencilla: JSON para la máquina, YAML para el humano. Si tu archivo es producido o consumido por un programa, elige JSON. Si se escribe y se relee a mano, elige YAML. Muchos ecosistemas aceptan ambos: Symfony lee YAML, JSON y XML para sus configuraciones, Kubernetes acepta los dos para sus manifiestos. En caso de duda, opta por YAML para la configuración humana y JSON para los flujos automatizados.

Puedes probar la conversión de un formato al otro con nuestro conversor JSON / YAML y formatear rápidamente un documento con el formateador JSON.

Preguntas frecuentes