Saltar al contenido
Rafhael Marsigli
8 min de lectura

Amo y odio JSON

Amo y odio JSON

Usar JSON como formato de configuración es (la mayoría de las veces) un error.

No es preferencia. No es estilo. Es un error arquitectural, y un error bien normalizado.

Esa frase incomoda porque JSON funciona. Y en tech, cuando algo funciona, tenemos una tendencia colectiva a dejar de preguntarnos si tiene sentido, y a empezar a construir una religión encima.

Seamos justos, JSON es un éxito gigantesco. Como formato de transporte, es casi imbatible: predecible, determinístico, aburrido de la forma correcta, trivial de parsear, trivial de generar, y está en todas partes. Máquina con máquina, JSON es genial. El problema empieza cuando tomamos un formato pensado para ser producido por computadoras, y decidimos que también debería ser escrito, leído, revisado, versionado y mantenido por humanos, como si nosotros también fuéramos una computadora, solo que más lenta.

No lo somos.

Y sí, “pero mi editor lo formatea” no es un argumento. Eso es como decir que una silla hecha de clavos está bien porque te compraste un buen pantalón.

Esto no es un ataque a JSON. Es un ataque al hábito de la industria de usar la herramienta correcta en el lugar equivocado, y después actuar sorprendida cuando las personas que escriben eso empiezan a odiar su propia vida.

Por qué ganó JSON

JSON no ganó por ser expresivo. Ganó por ser limitado, consistente y aburrido. Eso es una ventaja enorme cuando dos sistemas que no se conocen necesitan intercambiar datos sin negociar intención, contexto e interpretación.

Es un formato pequeño y cerrado. Sin atajos “creativos”. Sin “ah, pero en este caso”. Sin semántica mágica. Solo primitivos y estructura. Eso es exactamente lo que quieres para contratos. Cuando alguien dice “mi API habla JSON”, todos entienden al instante cuál es el acuerdo. Sin sorpresas. Sin interpretaciones creativas. Sin debates filosóficos nivel YAML sobre qué significa on.

Como formato de transporte, JSON merece todo el respeto que recibe.

Si el archivo lo genera una máquina, rara vez lo toca un humano, y está validado por un schema estricto, JSON en disco es aceptable. Mi problema es el JSON escrito por humanos fingiendo ser un formato amigable de autoría.

Do not feed the troll

Donde todo empieza a salir mal

En el momento en que decides que los humanos deberían “autorizar” JSON, estás diciendo, en la práctica: “la sintaxis importa más que la intención”. No lo dices en voz alta, pero eso es lo que pasa.

Esto generalmente no viene de maldad. Viene de pereza disfrazada de simplicidad: “el sistema consume JSON, así que las personas deben escribir JSON”. Parece lógico. Es también el tipo de lógica que crea dolor autoimpuesto a escala.

JSON exige precisión sintáctica absoluta para expresar la menor intención. Unas comillas que faltaron, una coma, un corchete, y todo se rompe. No existe “medio roto”. Existe “error de parseo” y se acabó la conversación.

Para las máquinas, eso está bien. Para los humanos, es hostil.

Y antes de que alguien mande un “skill issue”, ve a editar una policy grande de IAM en JSON a las 2 de la mañana, haz deploy, rompe producción, y después vuelve a dar charlas sobre cómo “es simple, en realidad”.

Do not forget the GODDAMN COMMA!

JSON es estructuralmente hostil para los humanos

Esto no es gusto. Es estructura.

JSON no tiene comentarios (en la especificación). JSON es verboso. JSON te obliga a repetirte. JSON te obliga a preocuparte por comas y comillas más que por el significado. JSON no tiene forma de expresar intención, solo estructura. Entonces las personas empiezan a inventar convenciones y supersticiones:

  • “esta clave es opcional, pero solo en este escenario”
  • “este valor es string, pero se comporta como enum, excepto cuando no”
  • “esta sección está deprecada, pero sigue siendo obligatoria por motivos”
  • “no toques este bloque si quieres paz”

Y como JSON no carga contexto, el contexto se escapa hacia afuera: README, Confluence, mensajes en Slack, conocimiento tribal, “pregúntale a Juan”. Tu configuración deja de ser configuración y se vuelve una búsqueda del tesoro.

Cuando ves un JSON grande escrito a mano, rara vez comunica claridad. Comunica resistencia. Comunica que alguien sufrió, y que la única razón por la que sigue existiendo es que todos acordaron fingir que esto es normal.

La configuración en JSON es un error normalizado

La configuración, por definición, es algo que los humanos van a leer, escribir, revisar, versionar y discutir en pull requests. Carga intención. Necesita contexto. Se beneficia de los comentarios. JSON no ofrece nada de eso, por diseño.

¿Entonces qué pasa? Creamos esos objetos hermosos de 300 líneas llenos de flags minúsculas, donde una coma puede invalidar todo, y después tiramos la “documentación” en otro lugar. Revisar se vuelve doloroso. Cambiar se vuelve aterrador. Y la experiencia final es básicamente “funciona, pero funciona impulsado por el rencor”.

Ejemplos que todo el mundo conoce:

  • tsconfig.json: no es el peor criminal, pero es la ilustración perfecta de “JSON escrito por un humano que quería comentarios desesperadamente”.
  • package.json: scripts, configs de herramientas, overrides, se vuelve un vertedero porque es conveniente, no porque sea bueno.
  • Cualquier config de política compleja (permisos, reglas, enrutamiento, workflows): JSON convierte el dominio en gestión de puntuación.

Y sí, puedes poner tooling. Puedes poner schema. Puedes poner validator. Puedes poner prettier. Puedes hacer una UI que genere JSON. ¿Notaste algo? Mientras más serio se vuelve el sistema, más alejas a los humanos de escribir JSON. Eso no es coincidencia. Es tu propia arquitectura admitiendo la verdad.

The good side

El argumento pro-JSON

“Pero JSON es simple. Todo el mundo lo sabe.”

Todo el mundo sabe un montón de cosas que son una herramienta pésima para ciertos trabajos.

Todo el mundo sabe regex también. Eso no significa que debamos almacenar reglas de negocio como string de regex dentro de un JSON y llamar a eso “configuración”. La familiaridad no es criterio para elegir una herramienta. La adecuación al problema sí.

JSON es simple de consumir, no simple de redactar. Y esa diferencia importa mucho más de lo que parece.

Los formatos de autoría existen por una razón

Si la config es para que los humanos la escriban, usa un formato pensado para humanos.

TOML existe por una razón. HCL existe por una razón. Hasta YAML existe por una razón, y sí, YAML tiene sus propios problemas, y cualquier persona que finja que YAML es “limpio” probablemente nunca depuró un edge case raro un viernes por la noche.

Pero el punto es: los formatos de autoría normalmente permiten comentarios, son más legibles, y reducen el costo cognitivo de escribir. Dejan que las personas piensen primero en el dominio, y después en la representación.

Y muchas herramientas “buenas” ya siguen este patrón:

Los humanos escriben algo expresivo. Las máquinas validan y normalizan. JSON solo aparece en los bordes, cuando necesita viajar, o cuando se convierte en un contrato estricto entre sistemas.

Esa separación no es burocracia. Es respeto por los límites humanos.

Well... Still better than legacy approaches

El pipeline que evita sufrimiento innecesario

En sistemas bien diseñados, el flujo suele ser:

  1. Los humanos redactan algo expresivo, cómodo y revisable.
  2. La máquina valida, transforma, normaliza.
  3. JSON aparece solo cuando hace falta: transporte, persistencia, interoperabilidad.

Si quieres configuración tipada, TypeScript puede ser genial, porque los tipos y el tooling trabajan a tu favor. Si quieres “configuración que las personas puedan leer y discutir”, TOML/YAML/HCL o un DSL pequeño suele ser una mejor elección. Si quieres un contrato entre sistemas, JSON sigue siendo el rey.

Este patrón aparece repetidamente en herramientas modernas porque funciona. Respeta las limitaciones humanas y explota las fortalezas de las máquinas. Forzar JSON desde el comienzo corta el camino saludable y empuja el costo hacia quien menos debería pagarlo.

The Json Cult

¿Hater o fan?

Todavía amo JSON donde tiene sentido: contratos, APIs, serialización, comunicación máquina con máquina.

Todavía odio JSON cuando alguien espera que escriba, revise y mantenga reglas complejas en él, como si eso fuera una experiencia humana aceptable.

Esto no es elitismo. No es moda. No es terquedad.

Es respeto básico por quien tiene que lidiar con el código.

JSON no necesita ser omnipresente para seguir siendo valioso. Solo necesita quedarse en el lugar correcto.

Y ese lugar definitivamente no es entre tú y el teclado a las 2 de la mañana, con el CI fallando, y alguien en Slack preguntando “¿y entonces, alguna novedad?”.

Empieza a escribir para encontrar algo.