JSON ↔ YAML ↔ TOML Converter

Tres formatos, tres filosofías de diseño

JSON, YAML y TOML son formatos de serialización de datos que representan básicamente la misma información — estructuras clave-valor anidadas, arrays, strings, números, booleanos — pero con prioridades distintas.

JSON fue diseñado para el intercambio entre máquinas: sintaxis mínima, parsing sin ambigüedades, sin comentarios. Todo parser JSON en cualquier lenguaje produce output idéntico para el mismo input. Es la lengua franca de las APIs.

YAML fue diseñado para la legibilidad humana: indentación significativa en lugar de corchetes, comentarios, strings multilínea sin escapado. Es el formato dominante para archivos de configuración en el ecosistema cloud-native (GitHub Actions, Docker Compose, manifiestos de Kubernetes, playbooks de Ansible).

TOML fue diseñado específicamente para archivos de configuración: tipado explícito, sin ambigüedad, sin espacios en blanco significativos. Es el formato de configuración nativo de proyectos Rust (Cargo.toml), packaging de Python (pyproject.toml) y sitios Hugo.

Cuándo usar cada formato

| | JSON | YAML | TOML | |---|---|---|---| | APIs REST / GraphQL | ✓ mejor | — | — | | GitHub Actions | — | ✓ mejor | — | | Docker Compose | — | ✓ mejor | — | | Manifiestos Kubernetes | — | ✓ mejor | — | | Cargo de Rust | — | — | ✓ mejor | | pyproject.toml de Python | — | — | ✓ mejor | | Config de app editada a mano | — | ✓ | ✓ | | Datos generados por máquina | ✓ mejor | — | — |

El problema Norway de YAML

YAML tiene una trampa de parsing bien conocida: los valores escalares sin comillas se interpretan por tipo. El código de país ISO de dos letras NO — que usa Noruega — se parsea como el booleano false en YAML 1.1. Del mismo modo, YES, ON, OFF, TRUE, FALSE, yes, no, on, off, true, false son todos booleanos en YAML 1.1.

# YAML 1.1 (usado por la mayoría de parsers antes de 2022)
country: NO      # parseado como boolean false — BUG
enabled: yes     # parseado como boolean true
debug: off       # parseado como boolean false

YAML 1.2 lo corrigió: solo true y false (minúsculas) son booleanos. Pero la mayoría de parsers (PyYAML, gopkg.in/yaml.v2 de Go, Psych de Ruby) aún usan por defecto el comportamiento 1.1. La solución segura: siempre entrecomillar strings que puedan malinterpretarse.

El tipado más estricto de TOML

TOML es deliberadamente inequívoco respecto a los tipos. Donde YAML infiere el tipo del valor, TOML requiere que seas explícito:

# TOML — los tipos no son ambiguos
name = "Alice"          # string
age = 30                # integer
height = 1.75           # float
active = true           # boolean
joined = 2024-01-15     # date (RFC 3339)
tags = ["rust", "dev"]  # array — todos los elementos deben ser del mismo tipo

Los arrays de TOML exigen tipos homogéneos (todos strings o todos integers — no mezclados). JSON y YAML permiten arrays heterogéneos. Esto significa que convertir [1, "two", true] de JSON a TOML requiere dividir en arrays tipados separados o rechazar la conversión — la herramienta marcará este caso.

Qué se pierde en la conversión

Comentarios

JSON no tiene comentarios. YAML y TOML sí. Al convertir YAML→JSON o TOML→JSON, todos los comentarios se pierden permanentemente. Si tu config YAML depende de comentarios para documentar valores, convierte una copia y conserva el original.

Orden de claves

Los objetos JSON son técnicamente desordenados. Los mappings YAML son similares. Las secciones TOML aparecen en el orden del documento. Al convertir entre formatos, el orden de las claves puede cambiar.

Strings multilínea

YAML tiene un soporte elegante para strings multilínea con | (bloque literal) y > (bloque plegado). TOML tiene strings básicos multilínea ("""…"""). JSON no tiene sintaxis para strings multilínea — usa secuencias de escape \n. Convertir un bloque literal YAML a JSON lo colapsa en un string de una sola línea con \n.

Ejemplos prácticos

Convertir un fragmento de Docker Compose a JSON:

# Input YAML
services:
  web:
    image: nginx:latest
    ports:
      - "80:80"
    environment:
      NODE_ENV: production

Se convierte en:

{
  "services": {
    "web": {
      "image": "nginx:latest",
      "ports": ["80:80"],
      "environment": {
        "NODE_ENV": "production"
      }
    }
  }
}

Convertir dependencias de Cargo.toml a YAML:

[dependencies]
serde = { version = "1.0", features = ["derive"] }
tokio = { version = "1", features = ["full"] }

Se convierte en:

dependencies:
  serde:
    version: "1.0"
    features:
      - derive
  tokio:
    version: "1"
    features:
      - full

Privacidad

Toda la conversión se ejecuta en tu navegador. El input nunca se envía a nuestros servidores. La herramienta usa js-yaml para parsear YAML e @iarna/toml para TOML — ambas son librerías MIT-licensed bien probadas.

¿Por qué mis valores booleanos de YAML se convierten con resultados inesperados?

Probablemente estás experimentando el problema Norway de YAML 1.1. En YAML 1.1 (aún el comportamiento por defecto de la mayoría de parsers), valores sin comillas como NO, YES, ON, OFF, True, False se tratan como booleanos en lugar de strings. Entonces country: NO se convierte en {"country": false} en JSON. La solución: entrecomilla los strings que puedan malinterpretarse — country: "NO" es inequívocamente un string en todas las versiones de YAML.

¿Se preservan los comentarios al convertir?

No. JSON no tiene sintaxis de comentarios, por lo que cualquier comentario de YAML o TOML se pierde al convertir a JSON. Al convertir YAML→TOML o viceversa, los comentarios también se pierden porque los parsers los descartan. Si tus archivos de config tienen comentarios importantes, conserva el original y trata el output convertido como un derivado separado.

¿Por qué TOML rechaza mi array de tipos mixtos?

TOML requiere que los arrays sean homogéneos — todos los elementos deben ser del mismo tipo. [1, "two", true] es válido en JSON y YAML pero inválido en TOML. Si necesitas tipos mixtos en TOML, usa un array de tablas inline: [{val = 1}, {val = "two"}]. Esta es una decisión de diseño deliberada en TOML para que los tipos sean inequívocos.

¿Puedo convertir un archivo YAML multi-documento (separado por ---)?

El YAML multi-documento (múltiples documentos en un archivo separados por ---) no está soportado en esta herramienta — solo convierte documentos únicos. Divide tu YAML multi-documento en archivos individuales primero, convierte cada uno y combínalos si es necesario.

El output JSON→YAML tiene comillas alrededor de valores que no las necesitaban. ¿Está mal?

No. YAML permite tanto strings con comillas como sin ellas. Un conversor que entrecomilla todos los strings produce YAML válido y conservador. Los strings sin comillas son una optimización de legibilidad, no un requisito. El valor parseado es idéntico en ambos casos.

¿Qué pasa con los valores JSON null al convertir a TOML?

TOML no tiene tipo null. Esta es una incompatibilidad real: JSON null no tiene equivalente directo en TOML. La herramienta omite las claves con valor null durante la conversión JSON→TOML y lo indica en el output. Si necesitas representar "ausente" en TOML, usa un valor sentinel o reestructura tus datos para simplemente omitir la clave.

¿Qué versión de YAML usa esta herramienta?

La herramienta usa semántica YAML 1.2 mediante js-yaml en modo estricto cuando es posible, lo que significa que solo true y false (minúsculas) se parsean como booleanos. Esto evita el problema Norway por defecto. Sin embargo, si pegas YAML generado por un parser 1.1 (PyYAML, Psych de Ruby), los valores pueden haber sido tipados incorrectamente en el origen — inspecciona el output JSON para verificar.

¿Es adecuado para YAML de Kubernetes o GitHub Actions?

Sí, para leer y entender esos archivos. Convertirlos a JSON o TOML es principalmente útil para procesamiento programático (por ejemplo, alimentar un manifest de Kubernetes a un script que espera JSON). No conviertas y luego intentes usar el resultado de vuelta como un manifest de Kubernetes — el YAML de Kubernetes tiene semánticas de campo específicas que requieren round-tripping cuidadoso.