Comparador JSON

Por qué el diff de JSON no es como el diff de texto

Cuando necesitas comparar dos versiones de un archivo JSON, la herramienta de diff de texto estándar —como git diff— puede resultar engañosa. El motivo es que git diff compara líneas de texto sin entender la semántica del JSON. Esto produce varios problemas:

• El orden de las claves importa artificialmente: {"a": 1, "b": 2} y {"b": 2, "a": 1} son el mismo objeto JSON, pero un diff de texto los mostrará como completamente diferentes.
• El formato afecta el resultado: si una versión está minificada y la otra está formateada con 4 espacios, el diff de texto mostrará diferencias en cada línea aunque los datos sean idénticos.
• La profundidad no se respeta: en un bloque de texto, cambiar un valor anidado dentro de un objeto grande puede hacer que el diff marque líneas irrelevantes como modificadas.

Un comparador JSON semántico resuelve estos problemas al parsear ambos documentos primero, normalizar el formato y ordenar las claves, y solo entonces comparar el resultado.

Casos de uso principales

Depuración de APIs

Cuando una API devuelve respuestas inesperadas, comparar la respuesta actual con la esperada (o con una respuesta anterior que funcionaba) es la forma más rápida de identificar qué campo cambió, qué se añadió o qué desapareció.

Gestión de configuración

Los archivos de configuración de aplicaciones en JSON (como package.json, tsconfig.json o configuraciones de herramientas) cambian con el tiempo. Comparar la versión actual con la versión de producción antes de desplegar ayuda a detectar cambios no intencionados.

Migraciones de datos

Al migrar datos entre bases de datos o actualizar esquemas, comparar un documento antes y después de la transformación confirma que la migración produjo exactamente los cambios esperados y no introdujo alteraciones inesperadas.

Revisión de código para respuestas de test

En las pruebas de integración o e2e, los fixtures JSON (respuestas esperadas) cambian cuando evoluciona la API. Un diff semántico facilita enormemente la revisión de esos cambios en pull requests.

Cómo funciona la normalización antes del diff

Antes de comparar, un buen comparador JSON realiza los siguientes pasos:

1. Parseo: valida que ambos lados sean JSON válido y construye la estructura de datos en memoria.
2. Ordenamiento de claves: ordena recursivamente todas las claves de objetos en orden alfabético. Esto garantiza que el orden de declaración no afecte al resultado.
3. Re-serialización: convierte la estructura de vuelta a texto con un formato consistente (indentación uniforme, un elemento por línea).
4. Diff de texto: aplica el algoritmo de diff estándar al texto normalizado.

El resultado es que solo las diferencias en los datos aparecen resaltadas, no las diferencias en formato u orden.

Casos edge a tener en cuenta

• Los arrays no se ordenan (el orden de los elementos en un array tiene semántica propia).
• Los valores null, false y 0 son distintos entre sí y no equivalentes.
• Los números como 1.0 y 1 pueden ser equivalentes o no dependiendo del parser; lo más seguro es ser consistente.