JSON, TOML, YAML o CSON: elegir un formato de configuración

En resumen: usa JSON para el intercambio entre máquinas y elige TOML o YAML para la configuración mantenida por humanos según el ecosistema (YAML para Kubernetes y CI, TOML para estructuras planas o fechas nativas); recurre a JSONC solo cuando no estés seguro de que el lector soporte el dialecto.

JSON existe para que las máquinas intercambien datos; un archivo de configuración lo escribe una persona para personas. Mezcla los dos y obtendrás un config.json que no admite comentarios y que nadie se atreve a recortar.

1. Empieza por dos tipos de archivo distintos

El intercambio de datos y la configuración no comparten el mismo objetivo, aunque la misma persona a menudo escriba ambos en la misma máquina.

JSON puntúa casi perfectamente en la columna izquierda: gramática mínima, un parser en cada lenguaje y sin comentarios significa que no existe el problema de "el comentario se alejó del valor". En la columna derecha, su rigor es pura fricción: sin comentarios, sin comas finales, sin fechas, y el texto multilínea tiene que colapsarse en una línea con \n.

2. Los cuatro contendientes y su sintaxis

• JSON: definido por RFC 8259 y ECMA-404, con exactamente seis tipos de valor: objeto, array, cadena, número, booleano y null. Es el estándar de intercambio de facto y el único formato que no necesita una decisión de selección.
• TOML: creado por Tom Preston-Werner, con v1.0.0 publicada en enero de 2021. Su objetivo declarado es un formato de configuración minimalista con semántica obvia que se mapea sin ambigüedad a una tabla hash. Cargo.toml y pyproject.toml lo usan de forma predeterminada.
• YAML: la especificación actual es 1.2.2. La indentación expresa la jerarquía, y soporta comentarios, anchors y múltiples documentos. Los manifiestos de Kubernetes, GitHub Actions y Ansible dependen de él, a costa de una especificación enorme y diferencias entre implementaciones.
• CSON: CoffeeScript Object Notation, que escribe configuración usando literales de objeto de CoffeeScript. El config.cson de Atom lo usaba. Soporta comentarios, claves sin comillas y comas finales, pero su ecosistema nunca salió del mundo JavaScript.

2.1 Comparación de capacidades

Dos celdas merecen una nota. TOML no tiene null, que es el fallo más común al convertir desde JSON. El comportamiento de "fecha nativa" de YAML significa que un parser 1.1 convierte 2026-10-31 en un objeto fecha automáticamente, así que el tipo deriva entre lenguajes.

3. Comentarios: la única debilidad de JSON

Primero la conclusión: si una persona mantiene el archivo y necesita explicar por qué un valor es lo que es, no uses JSON estándar.

Hay cuatro rutas prácticas, ordenadas de menos a más invasivas:

1. Cambiar a JSONC, que es JSON estándar más comentarios más comas finales. El settings.json de VS Code y tsconfig.json lo usan. El coste es que el lector debe usar un parser que entienda comentarios como jsonc-parser; JSON.parse simple falla. Los detalles están en JSON5 y JSONC: JSON con comentarios.
2. Mantener un documento sidecar. config.json sigue siendo legible por máquina, mientras que config.md explica qué significa cada campo y por qué contiene ese valor. Ambos viven en el mismo directorio y cambian en el mismo commit.
3. Poner las explicaciones en el schema. Las palabras clave description y $comment de JSON Schema pueden documentar campos, pero los schemas rara vez se distribuyen junto a la configuración de ejecución, así que quien lee la configuración puede que nunca las vea.
4. Pasar a TOML o YAML, dejando que el propio formato proporcione comentarios que todos los parsers entienden.

复制{
  // Fijado en 8080: el script de build del frontend lee este puerto para su proxy
  "port": 8080,
  // Desactivar la vigilancia para evitar agotar inodos en CI
  "watch": false
}

JSONC sigue siendo un dialecto: la extensión sigue siendo .json, pero solo algunas herramientas lo entienden. Cuando los datos salen del equipo o cruzan una frontera entre servicios, la línea entre JSONC y JSON estándar tiene que documentarse.

4. Fechas y cadenas multilínea: el terreno natural de TOML

TOML promueve la fecha y hora a un tipo de primera clase con cuatro variantes: fecha y hora con offset, fecha y hora local, fecha local y hora local. Las cadenas multilínea tienen sintaxis dedicada que conserva los saltos de línea:

复制title = "json-toolkit"
created = 2026-10-31T09:00:00+08:00
description = """
A JSON toolkit for developers.
Every operation runs locally in the browser.
"""

La misma información en JSON tiene que degradar la fecha a cadena y escapar los saltos de línea:

复制{
  "title": "json-toolkit",
  "created": "2026-10-31T09:00:00+08:00",
  "description": "A JSON toolkit for developers.\nEvery operation runs locally in the browser."
}

En JSON, "created" es solo una cadena que casualmente parece una fecha, así que la información de tipo tiene que vivir en un contrato de campos: ambas partes deben acordar que el campo es siempre RFC 3339. TOML le da al parser un objeto fecha real sin necesidad de acuerdo verbal.

YAML también puede contener texto multilínea, pero los dos estilos de bloque significan cosas distintas: | conserva los saltos de línea mientras que > los pliega en espacios. Elige el equivocado y una dirección o una sentencia SQL se colapsan en una sola línea, un error muy difícil de pillar en revisión.

5. Números: la diferencia más ignorada

La especificación de JSON no impone límite a la precisión numérica, pero RFC 8259 también advierte que la interoperabilidad es más segura cuando los números se tratan como doubles IEEE 754. En JavaScript, los enteros por encima de 2^53 - 1 pierden precisión en silencio:

复制JSON.parse('{"id":9007199254740993}').id
// 9007199254740992: el último dígito desaparece

TOML exige que los enteros de 64 bits con signo se manejen sin pérdidas y lancen un error en lugar de truncar en silencio; los floats siguen binary64 y también pueden ser inf o nan. YAML 1.1 arrastra una carga más antigua: 1:30 se parsea como 90 (sexagesimal), y los booleanos aceptan yes, no, on y off. De ahí el clásico "problema de Noruega", donde el código de país NO se convierte en false.

Para el dinero, nunca confíes en el punto flotante en ninguno de estos formatos: usa unidades mínimas enteras, cadenas o un tipo decimal de base de datos. El formateo y la precisión se tratan con más profundidad en Los límites de la conversión entre JSON, YAML y XML.

6. Tablas y anidamiento: los límites duros de TOML

TOML expresa el anidamiento con tablas y arrays de tablas:

复制[server]
port = 8080

[[routes]]
path = "/parse"
method = "POST"

[[routes]]
path = "/minify"
method = "POST"

Tiene dos límites duros que debes conocer antes de convertir:

• La raíz de un documento TOML es una tabla, así que un documento JSON cuyo nivel superior es un array (como [1, 2, 3]) no tiene representación TOML legal; debe envolverse como {"items": [...]};
• TOML no tiene null, así que un campo null de JSON debe eliminarse o reemplazarse por una cadena vacía o un valor centinela, empujando la semántica al consumidor.

YAML es lo contrario: la profundidad de anidamiento es ilimitada, y los anchors más las merge keys pueden reutilizar fragmentos:

复制defaults: &defaults
  retries: 3
  timeoutMs: 5000

server:
  <<: *defaults
  port: 8080

Los anchors son una capacidad exclusiva de YAML y una pérdida garantizada durante la conversión: JSON no tiene sintaxis de referencias, así que el archivo expandido crece y nada registra que las dos secciones solían ser la misma configuración.

7. Elegir por escenario

Una regla práctica: deja que el ecosistema elija el formato de configuración, no las preferencias personales. Escribir Rust significa Cargo.toml, desplegar en Kubernetes significa YAML y construir una extensión de VS Code significa JSONC. Solo en un proyecto nuevo sin restricciones de ecosistema "cuál es más agradable de escribir" es una pregunta real.

8. Límites de la conversión

Las herramientas de conversión garantizan los valores, nunca los comentarios. Así que no diseñes un pipeline bidireccional donde "JSON es la fuente y YAML es un artefacto de build". O generas en una sola dirección, o mantienes un único archivo fuente.

9. Lista de comprobación

• [ ] Documenta qué tipos de archivo usan qué formato, y enumera los dialectos permitidos;
• [ ] Prefiere TOML o YAML para configuración mantenida por humanos, y JSON para el intercambio entre máquinas;
• [ ] Guarda las fechas en JSON como cadenas RFC 3339 y marca el formato en el schema;
• [ ] Representa el dinero y los enteros por encima de 2^53 como cadenas o unidades mínimas, nunca como floats;
• [ ] Valida cada formato en CI con su propio parser, nunca con JSON.parse para YAML;
• [ ] Migra los formatos en una sola dirección, y borra el archivo antiguo para que los dos no puedan divergir.

FAQ

¿Por qué falla la conversión de JSON a TOML en algunos campos?

TOML no tiene null, y la raíz de un documento TOML es una tabla, así que un campo null de JSON debe eliminarse o reemplazarse por una cadena vacía o un centinela, y un array en el nivel superior debe envolverse como {"items": [...]}. Los comentarios, los tipos de fecha y inf/nan también se pierden al moverse en la dirección opuesta, y por eso la conversión debería ser unidireccional.

¿Debería mantener dos archivos de configuración en formatos distintos?

No. Las herramientas de conversión garantizan los valores pero nunca los comentarios, así que un pipeline donde "JSON es la fuente y YAML es un artefacto de build" acabará divergiendo. O generas en una sola dirección, o mantienes un único archivo fuente y borras el antiguo después de migrar.

¿Cómo añado comentarios a un archivo de configuración JSON?

El JSON estándar no tiene comentarios. Puedes cambiar a JSONC (el dialecto de VS Code, leído con jsonc-parser), mantener un documento sidecar que explique cada campo, o pasar a TOML o YAML. Los archivos que se envían a otros sistemas deberían seguir siendo JSON estándar, con las explicaciones en la documentación o en un schema.

¿Es mejor TOML o YAML para la configuración de aplicaciones?

Elige TOML cuando la estructura sea plana, mayormente pares clave-valor, y las fechas nativas importen; su semántica es más predecible y las diferencias entre parsers son menores. Elige YAML cuando necesites anidamiento profundo, múltiples documentos, reutilización con anchors, o cuando el ecosistema objetivo sea YAML-first, como Kubernetes o CI. Ambos soportan comentarios, así que el verdadero diferenciador es la complejidad estructural y el bloqueo del ecosistema.

¿Por qué NO se convierte en false en YAML?

YAML 1.1 trata yes, no, on, off, y y n como booleanos, así que el código de país de Noruega NO se parsea como false. Este es el "problema de Noruega". Evítalo usando una implementación que siga YAML 1.2, o poniendo entre comillas cualquier cadena que pueda malinterpretarse.

¿Sigue mereciendo la pena usar CSON?

No para proyectos nuevos. CSON depende del ecosistema CoffeeScript, tiene pocas herramientas mantenidas y un soporte limitado en editores y CI; después de que Atom dejara de mantenerse, sus casos de uso se redujeron aún más. Si un proyecto ya tiene configuración CSON, programa una migración puntual a JSON, TOML o YAML en lugar de añadir más.