Ordenar JSON

Ordena las claves de los objetos alfabéticamente, de forma recursiva por todos los objetos anidados. El orden de los arrays no se toca nunca, porque el orden de un array sí significa algo y el de las claves de un objeto no.

La razón para hacerlo son los diffs. Dos archivos con el mismo contenido en distinto orden de claves producen un diff lleno de ruido. Ordena ambos y el diff mostrará solo lo que cambió de verdad.

Cuándo ordenar es lo correcto

Antes de commitear un archivo generado

Archivos de bloqueo, configuración exportada y cualquier cosa que escriba una herramienta. Si el generador no garantiza un orden, ordenar hace que el archivo sea estable entre ejecuciones y entre máquinas.

Antes de comparar dos documentos

Ordenar ambos primero convierte un diff de texto en algo legible. Nuestro diff estructural ignora el orden de claves de todas formas, así que esto sirve sobre todo para herramientas que no lo hacen.

Para obtener una forma canónica

Hashear o firmar un documento exige una serialización determinista. Ordenar las claves es una parte; la RFC 8785, el JSON Canonicalization Scheme, especifica el resto, incluidos el formato de los números y el escapado de cadenas.

Cuándo ordenar es un error

Un archivo de configuración mantenido a mano donde el orden significa algo para quien lo lee: los ajustes importantes arriba, los relacionados agrupados. Ordenarlo alfabéticamente es técnicamente inofensivo y prácticamente molesto.

Cualquier cosa en la que un consumidor dependa del orden de las claves. No debería depender nadie, pero algunos parsers caseros lo hacen, y descubrirlo en producción sale caro.

Cómo funciona la comparación

Distingue mayúsculas de minúsculas por defecto, lo que coloca las mayúsculas antes que las minúsculas porque ese es su orden de puntos de código. Activa la comparación sin distinción de mayúsculas para obtener el orden que la gente suele esperar de una lista de nombres.

Ten en cuenta que esta es una ordenación por punto de código, no sensible a la configuración regional. Es determinista en todas partes, que es lo que necesita una forma canónica; una ordenación sensible a la localización produciría archivos distintos en máquinas distintas.

How to do this in code

Ordenar claves en código.

jq -S . input.json          # sort keys, recursively
jq -S -c . input.json       # sorted and compact

import json

# sort_keys applies recursively
out = json.dumps(json.loads(text), sort_keys=True, indent=2)

// The replacer only receives keys, so sorting needs a walk.
function sortDeep(value) {
  if (Array.isArray(value)) return value.map(sortDeep);
  if (value && typeof value === 'object') {
    return Object.fromEntries(
      Object.keys(value).sort().map((k) => [k, sortDeep(value[k])]),
    );
  }
  return value;
}

const out = JSON.stringify(sortDeep(JSON.parse(text)), null, 2);

// encoding/json sorts map keys automatically when marshalling
// a map. Struct fields keep their declaration order.
var v map[string]any
json.Unmarshal(data, &v)
out, _ := json.MarshalIndent(v, "", "  ")   // keys sorted

Preguntas frecuentes

¿Ordenar cambia mis datos?

Semánticamente no. Los objetos JSON no tienen orden según la especificación, así que un documento ordenado contiene el mismo valor. Sí cambia los bytes, que es justo el objetivo.

¿Por qué no se ordenan los elementos de los arrays?

Porque el orden de un array forma parte de los datos. Convertir [3,1,2] en [1,2,3] sería cambiar el documento, no reformatearlo.

¿Es esto lo mismo que JSON canónico?

Es una parte. La RFC 8785, el JSON Canonicalization Scheme, especifica además el formato de los números, el escapado de cadenas y la normalización Unicode, todo lo cual importa si vas a hashear o firmar el resultado.