Ordenar claves JSON

Quando dois JSONs representam os mesmos dados com chaves em ordens diferentes, um diff textual mostra falsas diferenças onde não há nenhuma diferença semântica. Isso polui reviews de pull request, quebra comparações automáticas em testes de snapshot e dificulta auditorias. Ordenar as chaves antes de salvar elimina esse ruído e torna os diffs realmente úteis.

A ordenação é recursiva: chaves de objetos aninhados são ordenadas também, e arrays de objetos têm as chaves de cada elemento reordenadas individualmente. Arrays puros de valores como strings ou números não são reordenados, porque a posição dos itens em um array é semanticamente significativa na maioria dos casos.

Em projetos com arquivos JSON persistidos, como mocks de API, fixtures de teste e arquivos de tradução i18n, manter chaves ordenadas como convenção facilita code review e reduz conflitos de merge quando múltiplos colaboradores ou ferramentas editam o mesmo arquivo. Algumas equipes impõem isso via lint com prettier, que oferece a opção de ordenar chaves JSON automaticamente ao salvar.

Uma ressalva técnica: a especificação ECMAScript não garante ordem de chaves em objetos. Na prática, porém, todos os motores modernos como V8, SpiderMonkey e JavaScriptCore preservam a ordem de inserção para chaves de string não numéricas. Após ordenar e re-parsear, a ordem se mantém. Para comunicação machine-to-machine isso é irrelevante, mas para leitura e diff humanos faz toda a diferença.

When two JSONs represent the same data with keys in different orders, a text diff shows false differences where there is no semantic difference at all. This pollutes pull request reviews, breaks automatic comparisons in snapshot tests, and complicates audits. Sorting keys before saving removes that noise and makes diffs genuinely useful.

The sort is recursive: keys in nested objects are sorted too, and arrays of objects have each element's keys reordered individually. Plain value arrays such as strings or numbers are not reordered, because item positions in an array are semantically significant in most cases.

In projects with persisted JSON files, such as API mocks, test fixtures, and i18n translation files, keeping keys sorted as a team convention makes code review easier and reduces merge conflicts when multiple contributors or tools edit the same file. Some teams enforce this via lint with prettier, which can sort JSON keys automatically on save.

A technical note: the ECMAScript spec does not guarantee key order in objects. In practice, however, all modern engines including V8, SpiderMonkey, and JavaScriptCore preserve insertion order for non-numeric string keys. After sorting and re-parsing, the order holds. For machine-to-machine communication this is irrelevant, but for human reading and diffing it makes all the difference.

Cuando dos JSONs representan los mismos datos con las claves en distinto orden, un diff textual muestra diferencias falsas donde no existe ninguna diferencia semántica. Esto ensucia las revisiones de pull request, rompe comparaciones automáticas en tests de snapshot y complica auditorías. Ordenar las claves antes de guardar elimina ese ruido y hace que los diffs sean realmente útiles.

El ordenamiento es recursivo: las claves de objetos anidados también se ordenan, y los arrays de objetos tienen las claves de cada elemento reordenadas individualmente. Los arrays de valores simples como cadenas o números no se reordenan, porque la posición de los elementos en un array es semánticamente significativa en la mayoría de los casos.

En proyectos con archivos JSON persistidos, como mocks de API, fixtures de pruebas y archivos de traducción i18n, mantener las claves ordenadas como convención del equipo facilita la revisión de código y reduce conflictos de merge cuando varios colaboradores o herramientas editan el mismo archivo. Algunos equipos lo imponen mediante lint con prettier, que puede ordenar claves JSON automáticamente al guardar.

Una nota técnica: la especificación ECMAScript no garantiza el orden de las claves en los objetos. En la práctica, sin embargo, todos los motores modernos como V8, SpiderMonkey y JavaScriptCore preservan el orden de inserción para claves de cadena no numéricas. Tras ordenar y volver a parsear, el orden se mantiene. Para comunicación entre máquinas esto es irrelevante, pero para la lectura humana y los diffs marca toda la diferencia.