JSON Viewer: deja de enseñar JSON crudo en tus demos

Escuchar artículo

Hay un momento muy triste en muchas demos técnicas: todo iba bien hasta que alguien dice “y aquí puedes ver la respuesta de la API”, y de repente aparece un bloque de JSON de miles de líneas ocupando toda la pantalla. Lo que debería demostrar valor acaba convertido en una sesión pública de scroll.

Ese problema también aparece fuera de las demos. Cuando estás depurando flujos complejos, validar un JSON grande a ojo es lentísimo. Encontrar el campo correcto, entender la relación entre datos anidados o enseñar el resultado a alguien no técnico se vuelve bastante más difícil de lo que debería.

De esa frustración salió JSON Viewer. No como “otro pretty-printer de JSON”, sino como una herramienta para separar tres piezas que normalmente mezclamos demasiado: datos, plantilla y preview. En cuanto haces esa separación, un JSON deja de ser un bloque crudo y pasa a ser una base sobre la que puedes construir una representación útil.

Esta misma idea conecta muy bien con el enfoque de Spec-Driven Development aplicado a herramientas como Strava CLI y JSON Viewer: primero contrato y comportamiento, luego implementación.

La idea: separar el dato de cómo lo enseñas

La idea del proyecto es sencilla:

Pegas un JSON.
Escribes una plantilla con Handlebars.
Ves el HTML resultante en tiempo real.

Eso suena pequeño, pero cambia bastante la experiencia. Ya no estás enseñando el dato como almacenamiento interno. Estás enseñando una interpretación visual del dato.

Aquí se ve mejor la idea en movimiento:

Por ejemplo, este JSON:

{
  "order_id": "ORD-99283",
  "customer": {
    "name": "Juan Pérez",
    "email": "juan@example.com"
  },
  "items": [
    { "id": 1, "product": "Monitor 4K", "price": 450, "status": "shipped" },
    { "id": 2, "product": "Teclado mecánico", "price": 120, "status": "processing" }
  ],
  "total": 570
}

Puede convertirse con una plantilla mínima en algo mucho más legible:

<section class="card">
  <h2>Pedido {{order_id}}</h2>
  <p>{{customer.name}} · {{customer.email}}</p>

  <ul>
    {{#each items}}
      <li>{{product}} - {{price}} EUR - {{status}}</li>
    {{/each}}
  </ul>

  <strong>Total: {{total}} EUR</strong>
</section>

No hay magia. Lo que hay es una decisión de diseño útil: dejar de tratar el JSON como interfaz de usuario.

Si te soy sincero, la parte que más valor aporta no es “cómo está hecha” por dentro, sino cómo cambia la conversación cuando dejas de enseñar JSON crudo.

Con este enfoque, el flujo pasa a ser muy directo: pegas datos reales, pruebas una plantilla simple y enseñas una vista que cualquier persona puede entender.

Y eso, en equipos mixtos (backend, frontend, producto), reduce bastante la fricción. En vez de discutir sobre llaves y arrays, pasas a discutir sobre significado y decisiones.

Por qué elegí plantillas simples

Aquí había varias opciones. Podía construir una UI con mapeo manual de campos, podía intentar algo parecido a JSX dinámico, o podía usar un motor de plantillas clásico.

Me quedé con Handlebars por tres razones bastante pragmáticas:

La sintaxis es fácil de leer incluso para alguien que no trabaja a diario con frontend.
Resuelve bien interpolación, iteraciones y condicionales simples.
La plantilla es texto puro, así que es fácil de guardar, compartir y editar.

Si hubiese usado JSX, habría ganado expresividad, pero también habría subido mucho la barrera de entrada. Para este caso, más poder no significa mejor experiencia.

Decisiones que mejoran la experiencia

No elegí las piezas por moda. Las elegí para que la herramienta se sintiera ligera y útil desde el primer minuto.

Plantillas fáciles de tocar: si una persona del equipo no trabaja en frontend, aun así puede editar y entender lo que ve.
Editor cómodo: cuando pegas JSON grande, un buen editor no es un lujo. Es la diferencia entre avanzar o desesperarte.
No perder el trabajo: si cierras pestaña o refrescas, no empiezas de cero.

Para mí, ese combo mantiene el foco donde debe estar: entender y comunicar datos, no pelearte con la herramienta.

Plantilla simple vs plantilla más útil

Una de las cosas que más ayudan a entender el proyecto es ver la diferencia entre una plantilla mínima y una pensada para comunicar.

Ejemplo simple:

<pre>{{this}}</pre>

Sirve poco. Apenas cambia nada.

Ejemplo más útil:

<article class="rounded border p-4">
  <header class="mb-4">
    <h1 class="text-xl font-bold">Pedido {{order_id}}</h1>
    <p>{{customer.name}} · {{customer.email}}</p>
  </header>

  <ul class="space-y-2">
    {{#each items}}
      <li class="flex justify-between rounded bg-slate-50 p-2">
        <span>{{product}}</span>
        <strong>{{price}} EUR</strong>
      </li>
    {{/each}}
  </ul>

  <footer class="mt-4 text-right">
    Total: {{total}} EUR
  </footer>
</article>

Aquí ya hay una intención clara: resumir, jerarquizar y resaltar lo importante. Ese es el tipo de salto que buscaba con la herramienta.

Casos de uso reales más allá de la demo

Aunque el proyecto nació de la frustración de enseñar JSON en presentaciones, enseguida vi otros usos bastante prácticos:

Probar rápidamente distintas vistas para una respuesta de API.
Enseñar contratos de datos a perfiles no técnicos sin arrastrarlos a leer JSON crudo.
Depurar estructuras anidadas en integraciones.
Generar mockups rápidos de cómo podría verse cierta información en una UI real.

No sustituye una aplicación final, claro. Pero sí sirve muy bien como herramienta puente entre backend, frontend y producto.

Lo que aprendí usándolo de verdad

Aquí es donde el proyecto dejó de ser una idea bonita y se volvió más real.

1. Una plantilla también puede volverse un lío

En cuanto ves que Handlebars permite condicionales e iteraciones, apetece resolver todo ahí. Mala idea. Si la plantilla concentra demasiada lógica, deja de ser una capa de presentación y se convierte en algo difícil de mantener.

2. Un error claro vale más que una pantalla bonita

Una interfaz bonita puede hacer que suavices demasiado los fallos. Para una herramienta de este tipo, eso es contraproducente. Si algo rompe, mejor enseñar un error claro que un preview vacío y silencioso.

3. No todo JSON merece una card

No todos los datos piden la misma representación. A veces una card funciona. Otras veces hace falta tabla, árbol o una agrupación previa. La herramienta ayuda, pero no elimina la necesidad de pensar cómo contar la información.

Limitaciones y siguientes mejoras

También hay límites bastante claros:

La calidad del resultado depende de lo bien que esté pensada la plantilla.
No resuelve transformaciones complejas de datos por sí solo.
Si el JSON es enorme, la experiencia del editor y del render puede degradarse.
Handlebars cubre muy bien los casos simples, pero no pretende ser un motor de UI completo.

Si siguiera iterándolo, me centraría en:

Plantillas iniciales listas para tipos de JSON frecuentes.
Mejor ayuda cuando falla el JSON o la plantilla.
Vistas rápidas según el caso: tabla, card, lista o resumen.

Qué haría yo si empezara hoy

Si arrancara esta herramienta desde cero otra vez, me centraría en tres cosas:

Elegir una plantilla fácil de aprender para que cualquiera del equipo pueda usarla.
Cuidar mucho el editor, porque ahí ocurre casi toda la experiencia.
Priorizar ejemplos reales de uso por encima de detalles internos.

Para mí, ese es el aprendizaje más útil del proyecto. JSON Viewer no va de “poner bonito un JSON”, sino de reconocer que un dato bruto y una representación útil son capas distintas. En cuanto diseñas esa separación, depurar, enseñar y explorar respuestas de API se vuelve mucho menos doloroso.

El proyecto sigue siendo de código abierto y está en GitHub, pero el valor real no está en el repo. Está en la idea que puedes reutilizar mañana mismo: separa dato, plantilla y preview, y muchas tareas de demo y debugging empiezan a tener bastante más sentido.

Si estás construyendo con IA, te recomiendo complementar este artículo con un flujo práctico para explorar, planificar y ejecutar sin alucinaciones.

Preguntas frecuentes

¿JSON Viewer reemplaza a una herramienta de documentación de APIs?

No. Sirve más como herramienta de exploración, demo y debugging. Para documentación formal seguiría usando OpenAPI, ejemplos versionados o documentación técnica.

¿Necesito saber React para usarlo?

No. La idea es que puedas trabajar con JSON y una plantilla sencilla sin tocar el código interno de la aplicación.

¿Por qué usar Handlebars y no JSX?

Porque Handlebars tiene menos barrera de entrada. Para este caso interesa transformar datos en una vista rápida, no construir una aplicación completa.

¿Qué tipo de JSON encaja mejor?

Respuestas de API, pedidos, perfiles, eventos, logs estructurados o cualquier dato que tenga una forma clara pero sea incómodo de leer en bruto.

¿Puedo usarlo con datos sensibles?

Sí, sobre todo si trabajas en local y tienes claro qué datos pegas. Aun así, si no es necesario, mejor usar datos anonimizados o ejemplos sin información de clientes.