Cómo comparar dos archivos JSON y encontrar qué cambió

La forma más rápida de comparar dos archivos JSON es pegar ambos en una herramienta de diff lado a lado, darles el mismo formato y leer las líneas que resalta. La parte difícil generalmente no es la comparación. Es el ruido: claves reordenadas, indentación diferente y comas finales perdidas pueden hacer que dos archivos casi idénticos parezcan no compartir nada en común.

Esta guía explica cómo obtener un diff limpio y confiable. Veremos por qué los archivos JSON se distancian en papel mientras permanecen iguales en significado, los pocos métodos que vale la pena conocer, y un ejemplo práctico que puedes seguir. Si solo quieres la herramienta, nuestra página de comparación JSON hace todo esto en el navegador.

Por qué los archivos JSON son engañosamente difíciles de comparar

JSON tiene una gramática pequeña y estricta (consulta la especificación en json.org), pero da a los escritores mucha libertad sobre cómo disponer el texto. Dos archivos pueden describir el mismo objeto exacto y aun así diferir byte a byte. Un diff de texto plano no sabe nada de eso, así que lo marca todo fielmente.

Esto es lo que debes interiorizar antes de empezar: las claves de objeto en JSON no tienen orden. La especificación (RFC 8259) define un objeto como un conjunto desordenado de pares nombre/valor. Entonces {"name":"Ada","id":7} y {"id":7,"name":"Ada"} son iguales, aunque un diff de líneas los pinte de rojo y verde.

Parece un cambio, pero casi nunca lo es

Lo que ves en el diff	¿Es un cambio real?	Qué hacer
Claves en orden diferente	No, los objetos no tienen orden	Ordena las claves en ambos lados
Indentación de 2 vs 4 espacios	No	Formatea ambos lados igual
Minificado vs pretty-printed	No	Formatea ambos lados
Salto de línea al final del archivo	No	Ignóralo o elimina el espacio en blanco
Un valor cambió de "7" a 7	Sí, cadena vs número	Investígalo, es real
Elementos de array en diferente orden	Quizás, los arrays sí tienen orden	Decide si el orden importa aquí

Esa última fila confunde a la gente. Los arrays mantienen su orden, los objetos no. Así que [1, 2, 3] y [3, 2, 1] son genuinamente diferentes, pero las claves dentro de un objeto pueden barajarse libremente. Si quieres el detalle técnico sobre cómo JavaScript parsea todo esto, MDN tiene una sólida referencia sobre el objeto JSON.

Cuatro formas de comparar JSON y cuándo usar cada una

No existe un único método mejor. Depende de dónde estén los archivos y qué quieres descubrir. Así se comparan las opciones más comunes.

Método	Mejor para	Esfuerzo	¿Entiende JSON?
Revisión visual	Archivos pequeños, uno o dos campos	Bajo	No, tú eres el parser
Herramienta diff online	Verificaciones rápidas, pegar desde cualquier lugar	Bajo	Con formato y orden de claves, sí
Línea de comandos (jq, diff)	Archivos en disco, scripting, archivos grandes	Medio	Sí, cuando ordenas primero
IDE o git diff	Archivos ya en un repositorio	Bajo si está confirmado	Basado en líneas por defecto

Para la mayoría de las personas, una herramienta de navegador gana en velocidad porque no hay nada que instalar y puedes pegar un fragmento directamente desde un log o una llamada de API. El problema es el ruido de formato, que manejaremos a continuación. Si vives en la terminal, jq es la herramienta que debes aprender, y mostraremos la única bandera que importa.

La comparación limpia más rápida, paso a paso

Esta es la rutina que uso cuando alguien me da dos archivos de configuración y pregunta "¿qué es diferente?" Tarda unos quince segundos.

1. Abre la herramienta de comparación JSON.
2. Pega el original a la izquierda y la nueva versión a la derecha.
3. Haz clic en Formato en ambos lados para que compartan la misma indentación.
4. Activa ordenar claves (canonicalizar) para que las claves reordenadas dejen de aparecer como cambios.
5. Lee el resultado. El verde es añadido, el rojo es eliminado, y un valor modificado aparece como uno de cada color.

Los pasos tres y cuatro son todo el truco. Una vez que ambos archivos están formateados de forma idéntica y sus claves están ordenadas, lo único que queda por resaltar es lo que realmente cambió. Nuestro motor de diff está construido sobre el diff-match-patch de Google, que compara línea por línea primero para que sea rápido incluso en archivos largos.

Un ejemplo práctico

Supón que estás revisando un cambio en un registro de usuario. Aquí está el antes:

{
  "name": "Ada Lovelace",
  "role": "editor",
  "active": true,
  "seats": 3
}

Y aquí está el después, tal como te lo entregó un compañero:

{
  "active": true,
  "name": "Ada Lovelace",
  "role": "admin",
  "seats": 5,
  "team": "platform"
}

Mete esos en un diff de líneas crudo y parece que casi todas las líneas se movieron, porque las claves están en orden diferente. Formatea y ordena ambos, y la historia real es breve:

Lo que realmente cambió

Campo	Antes	Después	Cambio
role	editor	admin	Modificado
seats	3	5	Modificado
team	—	platform	Añadido
name	Ada Lovelace	Ada Lovelace	Sin cambios
active	true	true	Sin cambios (solo se movió)

Tres ediciones reales: un cambio de rol, un conteo de asientos y un nuevo campo de equipo. El reordenamiento era ruido. Ese ascenso de editor a admin es el tipo de cosa que quieres detectar en revisión, y es fácil perdérselo cuando está enterrado bajo veinte líneas de falsos positivos.

Eliminar el ruido de formato en la línea de comandos

Si tus archivos ya están en disco, la misma idea de "formatear y ordenar" funciona con dos comandos cortos. La bandera -S le dice a jq que ordene las claves de objeto; pasar ambos archivos por ella los normaliza para que un diff simple sea honesto:

jq -S . old.json > old.sorted.json
jq -S . new.json > new.sorted.json
diff old.sorted.json new.sorted.json

Ahora diff solo reporta valores que realmente cambiaron, porque ambos archivos tienen la misma indentación y el mismo orden de claves. Este es el equivalente en terminal de hacer clic en Formato y ordenar claves en el navegador.

Diff de texto vs diff estructural

Todo lo anterior es un diff de texto: rápido, visual y perfecto para que una persona lea un cambio. Un diff estructural va más lejos y describe el cambio como datos. El estándar para eso es JSON Patch, definido en RFC 6902, que expresa ediciones como operaciones como replace y add en una ruta dada. Quieres un diff estructural cuando un programa necesita aplicar el cambio, no solo una persona revisándolo visualmente. Para la revisión diaria, un diff de texto con claves ordenadas es suficiente.

Errores comunes que debes vigilar

Error	Por qué duele	Solución
Precisión de números	Los enteros por encima de 2^53 − 1 pierden precisión en JavaScript	Compara IDs grandes como cadenas; ver MAX_SAFE_INTEGER
Escapes Unicode	"café" y "café" son la misma cadena, diferentes bytes	Formatea ambos lados, lo que normaliza la codificación
Claves duplicadas	La mayoría de los parsers conservan la última silenciosamente	Valida el JSON antes de confiar en el diff
Comas finales	No son JSON válido; un archivo puede no parsearse	Corrige la sintaxis primero, el validador lo marcará
Cadena vs número	"5" y 5 parecen iguales pero son tipos diferentes	Este es un cambio real, no lo descartes

Herramientas relacionadas

JSON rara vez es el único formato con el que trabajas. Si estás comparando configuración entre entornos, comparar YAML aplica la misma idea a YAML. Revisar cambios entre dos llamadas de API es para lo que está hecho el diff de respuestas de API, y los cambios de dependencias son más fáciles de leer en la página de diff de package.json.