Ordenar JSON

Ordena as chaves dos objetos em ordem alfabética, recursivamente por todo objeto aninhado. A ordem dos arrays nunca é tocada, porque a ordem de um array significa algo e a das chaves de um objeto não.

O motivo para fazer isso são os diffs. Dois arquivos com o mesmo conteúdo em ordem de chaves diferente geram um diff cheio de ruído. Ordene os dois e o diff mostra só o que realmente mudou.

Quando ordenar é a jogada certa

Antes de commitar um arquivo gerado

Lock files, configuração exportada e qualquer coisa que uma ferramenta escreva. Se o gerador não garante uma ordem, ordenar deixa o arquivo estável entre execuções e entre máquinas.

Antes de comparar dois documentos

Ordenar os dois primeiro transforma um diff de texto em algo legível. O nosso diff estrutural ignora a ordem das chaves de qualquer forma, então isto serve sobretudo para ferramentas que não ignoram.

Para obter uma forma canônica

Fazer hash ou assinar um documento exige uma serialização determinística. Ordenar as chaves é uma parte; a RFC 8785, o JSON Canonicalization Scheme, especifica o resto, incluindo formatação de números e escape de strings.

Quando ordenar é a jogada errada

Um arquivo de configuração mantido à mão em que a ordem carrega significado para quem lê: as opções importantes no topo, as relacionadas agrupadas. Ordenar isso alfabeticamente é tecnicamente inofensivo e praticamente irritante.

Qualquer coisa em que um consumidor dependa da ordem das chaves. Ninguém deveria depender, mas alguns parsers caseiros dependem, e descobrir isso em produção sai caro.

Como a comparação funciona

Diferencia maiúsculas de minúsculas por padrão, o que coloca as maiúsculas antes das minúsculas porque essa é a ordem dos pontos de código. Ligue a comparação sem diferenciar caixa para obter a ordem que as pessoas costumam esperar de uma lista de nomes.

Note que esta é uma ordenação por ponto de código, não sensível a localidade. Ela é determinística em qualquer lugar, que é o que uma forma canônica precisa; uma ordenação sensível a localidade produziria arquivos diferentes em máquinas diferentes.

How to do this in code

Ordenando chaves em 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

Perguntas frequentes

Ordenar altera os meus dados?

Semanticamente não. Objetos JSON não têm ordem segundo a especificação, então um documento ordenado carrega o mesmo valor. Ele altera os bytes, que é justamente o objetivo.

Por que os elementos dos arrays não são ordenados?

Porque a ordem de um array faz parte dos dados. Transformar [3,1,2] em [1,2,3] seria alterar o documento, não reformatá-lo.

Isto é o mesmo que JSON canônico?

É uma parte disso. A RFC 8785, o JSON Canonicalization Scheme, também especifica formatação de números, escape de strings e normalização Unicode, tudo isso importante se você for fazer hash ou assinar o resultado.