La solicitud de extracción tenía 240 líneas cambiadas y había tocado exactamente dos valores. Ese fue el momento en que me tomé en serio la clasificación de claves JSON. Un compañero de equipo había ejecutado un archivo de configuración a través de un formateador que reordenaba sus claves, yo había editado dos de esos valores a mano y la diferencia resultante era una pared ilegible de rojo y verde donde 238 de las líneas eran claves que simplemente se habían movido. Mi crítico, comprensiblemente, me pidió que lo rehiciera. Los cambios reales eran invisibles dentro del ruido.
Ejecuto [Toolz.dev](/ y también construyo proyectos de Laravel y WordPress, lo que significa que vivo adentro package.json, composer.json, tsconfig.json, catálogos de traducción y cien otros archivos JSON que se comprometen al control de versiones. Un archivo JSON con un orden de claves impredecible es un impuesto pequeño y recurrente para cada uno de ellos. Ordenar claves en un orden alfabético estable es la solución, y es uno de esos cambios que parece cosmético hasta la primera vez que le ahorra una revisión de código desperdiciada. Esta guía cubre cuándo ordenar las claves JSON, cuándo no hacerlo y cómo hacerlo sin romper nada.
TL;Dr: Un clasificador JSON reordena un objeto 's en orden alfabético y vuelve a serializar el resultado. El orden de las claves no cambia lo que significa JSON, porque el estándar JSON desorden los objetos, pero un orden consistente hace que los archivos sean legibles y produce diferencias limpias de control de versiones que solo muestran valores modificados. Ordene recursivamente para llegar a objetos anidados, mantenga el orden de las matrices de forma predeterminada porque las matrices están ordenadas y elija salida ascendente o descendente, bonita o minificada. El Clasificador JSON se ejecuta completamente en su navegador.
¿qué es un clasificador JSON?
Un clasificador JSON toma un objeto JSON y reorganiza sus claves en orden alfabético, luego vuelve a escribir el objeto. Los valores no se tocan. Sólo cambia la secuencia en la que aparecen las claves, y eso es seguro porque RFC 8259 define un objeto como una colección desordenada: reordenar claves no puede cambiar lo que significa el documento. Entonces {"name":"toolz","author":"Liton"} se convierte en {"author":"Liton","name":"toolz"}. De forma predeterminada, la clasificación es recursiva, lo que significa que las claves dentro de cada objeto anidado también están ordenadas, hasta el nivel más profundo.
Esa es toda la operación, y su simplicidad es el punto. No estás transformando datos, validando un esquema o convirtiendo un formato. Estás imponiendo un orden predecible a algo que tenía uno arbitrario. Todos los demás beneficios, legibilidad, comparabilidad, diferencias limpias, fluyen de ese único orden predecible.
¿Las claves de ordenación cambian lo que significa mi json?
No, y este es el hecho que hace que la clasificación sea segura. En el estándar JSON, ECMA-404, un objeto se define como una colección desordenada de pares de nombres y valores. La especificación es explícita de que el orden de esos pares no es significativo. Cualquier analizador conforme lee {"a":1,"b":2} y {"b":2,"a":1} como exactamente los mismos datos. Cuando tu programa lo hace config.timeout investigaciones operacionales data["name"], busca la clave por su nombre; nunca le importa en qué parte del objeto se escribió esa clave.
Hay una advertencia que vale la pena decir claramente, porque alguien siempre pregunta. Una pequeña cantidad de sistemas abusan de los objetos JSON como si estuvieran ordenados, dependiendo del orden de inserción para su visualización o procesamiento. Eso es un mal uso del formato en lugar de una propiedad del mismo, pero si está alimentando un sistema que no controla, pruebe antes de enviar un archivo ordenado a una canalización que no puede inspeccionar. Para la inmensa mayoría de JSON, archivos de configuración, cargas útiles de API, archivos de bloqueo, catálogos de traducción y claves de clasificación del mundo real es un cambio puramente de presentación sin efecto sobre el significado.
Las matrices son el caso opuesto y la distinción importa. Una matriz JSON está ordenada por definición y su orden frecuentemente tiene significado: una secuencia de pasos, una lista clasificada, un conjunto de coordenadas donde la posición uno es longitud y la posición dos es latitud. Reordenar una matriz puede cambiar silenciosamente lo que dicen los datos. Es por eso que esta herramienta conserva el orden de las matrices de forma predeterminada y solo clasifica las matrices cuando se lo solicita explícitamente, e incluso entonces solo para matrices cuyos elementos son todas cadenas o todos números.
¿Por qué ordenaría las claves JSON?
La razón principal es la diferencia limpia, y es la que cambió mi forma de trabajar. Las herramientas de control de versiones comparan archivos línea por línea. Cuando dos archivos que representan los mismos datos escriben sus claves en diferentes órdenes, la diferencia está llena de claves que se movieron en lugar de valores que cambiaron. Adopte una regla según la cual cada archivo JSON se escribe con claves ordenadas y el problema desaparece: dos versiones del archivo difieren solo cuando un valor realmente difiere, por lo que un revisor ve el cambio real de inmediato. Esta es exactamente la razón por la que muchos linters y formateadores ofrecen una opción de claves de clasificación y por qué herramientas como jq envíe una bandera de claves de clasificación.
La segunda razón es la legibilidad humana. Cuando escanea un archivo de configuración grande en busca de una configuración específica, el orden alfabético le indica dónde buscar. No lees el archivo completo; saltas aproximadamente a donde debería estar la clave, como lo harías en un diccionario. En un archivo con ochenta claves, esa es la diferencia entre una búsqueda de dos segundos y un escaneo completo.
La tercera razón es la comparabilidad entre archivos. Si su proyecto tiene diez archivos JSON que deberían compartir una estructura común, ordenarlos todos de la misma manera hace que sea trivial ver si a uno le falta una clave o si tiene una adicional. Las divergencias se alinean una al lado de la otra en lugar de esconderse en diferentes posiciones.
La cuarta razón es la canonicalización. Algunos flujos de trabajo necesitan una representación estable y determinista de un valor JSON, por ejemplo para hash, almacenarlo en caché o comparar dos cargas útiles para lograr igualdad, independientemente de cómo se serializaron. Ordenar claves es un paso hacia una forma canónica, aunque un JSON canónico completo también normaliza los espacios en blanco y el formato de números.
¿cómo uso el clasificador JSON?
Pegue su JSON en el cuadro de entrada del Clasificador JSON, o cargue la muestra para ver la forma de la salida. La entrada debe ser JSON válida. Si no es así, la herramienta informa el error de análisis con su posición para que pueda arreglar una coma perdida o un corchete no cerrado antes de ordenar.
Luego elija cómo se ejecuta la clasificación. Elija ascendente, que es de A a Z, o descendente para Z a A. Decida si se debe doblar el caso, que está activado de forma predeterminada para que Name, namey NAME siéntese juntos en lugar de separarse porque las letras mayúsculas se clasifican antes que las minúsculas en orden de caracteres sin formato. Elija si desea descender a objetos anidados, que casi siempre desea, o ordenar solo el nivel superior. Si también desea ordenar matrices de cadenas o números, active la clasificación de matrices; Las matrices mixtas y las matrices de objetos siempre se dejan como están.
Finalmente, elige tu estilo de salida. Imprima bonitamente con sangría de dos, cuatro espacios o pestañas para un archivo legible que confirmará, o minifíquelo en una sola línea para obtener la carga útil más pequeña para almacenamiento o transporte. Ejecute el tipo y luego copie el resultado o descárguelo. El recuento de claves le indica cuántas claves se reordenaron, lo cual es una verificación rápida de cordura de que la herramienta vio la estructura que esperaba.
Ascendente, descendente, recursivo: ¿qué configuraciones quiero?
La mayoría de las veces, los valores predeterminados son los que desea: ascendente, recursivo, que no distingue entre mayúsculas y minúsculas, bastante impreso con dos espacios. Eso produce el archivo legible y compatible con diferencias que motiva la clasificación en primer lugar. Las otras configuraciones existen para situaciones específicas y la siguiente tabla es cómo decido.
| Configuración | Predeterminado | Cuándo cambiarlo |
|---|---|---|
| Orden | Ascendente (A a Z) | Descender es raro; útil cuando desea que las claves más recientes o de mayor prioridad, nombradas para ordenar al final, estén en la parte superior |
| Recursivo | En | Desactívelo solo cuando desee reordenar secciones de nivel superior pero conserve el orden ajustado a mano dentro de cada una |
| Ignorar caso | En | Desactívelo cuando necesite un orden estricto de puntos de código, por ejemplo, para que coincida con otra herramienta que clasifique el caso de forma sensible |
| Ordenar matrices | Apagado | Actívelo para matrices que son conjuntos genuinamente desordenados, como una lista de etiquetas o valores permitidos |
| Bonito estampado | En | Apáguelo para minificar para transporte o almacenamiento |
La única configuración que la gente utiliza indebidamente es la clasificación de matrices. Actívelo sólo cuando esté seguro de que una matriz representa un conjunto desordenado. Es seguro ordenar una lista de etiquetas, un conjunto de extensiones de archivos permitidas o una bolsa de indicadores de características. Una lista de pasos de canalización, una tabla de rutas o cualquier cosa donde la posición implique secuencia no lo sea. En caso de duda, deje las matrices en paz, porque el valor predeterminado de la herramienta ' de preservar el orden nunca puede dañar sus datos, mientras que ordenar la matriz incorrecta en silencio sí puede hacerlo.
¿cómo encaja esto con otras herramientas JSON?
La clasificación suele ser un paso en una cadena pequeña. Cuando JSON llega minificado e ilegible desde una API, lo ejecuto a través de Formateador JSON primero para sangrarlo y validarlo, luego ordene las claves para que sea escaneable. Cuando estoy preparando una carga útil para el transporte después de clasificarla, el Minifier JSON lo reduce a una sola línea y, como las claves ya están ordenadas, dos cargas útiles minificadas que representan los mismos datos salen idénticas byte por byte, lo cual es útil para almacenar en caché y comparar.
Para trabajos estructurales más que para presentaciones, el Aplanador JSON convierte objetos anidados en claves punteadas y viceversa, que se emparejan naturalmente con la clasificación cuando se está disputando la configuración en variables de entorno. Y cuando necesitas los datos en otro formato completamente diferente, el Convertidor JSON a YAML es la siguiente parada; ordenar claves antes de convertir también le brinda un archivo YAML con un orden de campo predecible y legible. Si quieres tener una idea más amplia de cómo encajan, diseñé mi configuración completa en Guía del kit de herramientas para desarrolladores web, y la mecánica más profunda del formato en vivo en el Guía de formateador JSON.
Un ejemplo real: domesticar un paquete.json diff
Permítanme analizar la situación exacta que inició este artículo, porque muestra por qué son importantes las opciones de configuración. Tuve un package.json donde el dependencies el bloque se había escrito en orden de instalación, aproximadamente en el orden en que se agregaron los paquetes durante dos años. Un nuevo miembro del equipo ejecutó su editor 's format-on-save, que clasificó las claves de dependencia y las comprometió junto con un cambio genuino: pasar un paquete de la versión 4 a la versión 5.
La diferencia fue un desastre. Cada dependencia debajo de la afectada parecía haberse movido, porque la clasificación había cambiado sus posiciones, por lo que el revisor vio treinta líneas cambiadas para lo que era una actualización de una línea. La solución no era discutir sobre quién era el editor correcto. La solución era ordenar el archivo una vez, confirmar ese tipo como su propio cambio separado con un mensaje como "sort package.json keys," y luego hacer que la versión subiera al orden ahora estable. Después de eso, cada cambio de dependencia futuro produjo una diferencia limpia de una o dos líneas, porque el archivo ya estaba en el orden en el que todos querían colocarlo.
Ese es el patrón que sigo ahora para cualquier JSON que viva en control de versiones. Ordenarlo una vez en una confirmación dedicada y luego mantenerlo ordenado. El Clasificador JSON con sus valores predeterminados, ascendente y recursivo, produce exactamente el orden en que Prettier's ordena la opción y jq --sort-keys produce, por lo que el archivo se mantiene estable sin importar qué herramienta ejecute un compañero de equipo. Lo único que compruebo primero son las matrices: package.json no tiene matrices significativas de las que preocuparse, pero un archivo con una matriz ordenada como una lista de pasos de compilación necesita que se omita la clasificación de matrices, que es la predeterminada, por lo que la secuencia sobrevive.
¿qué herramientas y formatos clasifican las claves JSON?
Ordenar claves JSON es una necesidad lo suficientemente común como para aparecer en todo el ecosistema, lo cual es una buena señal de que la práctica es sólida y no una peculiaridad personal. El procesador de línea de comandos jq tiene un --sort-keys bandera, a menudo escrita -S, que ordena las claves de cada objeto en su salida. El formateador de código Prettier puede ordenar claves en JSON a través de su configuración. Muchos linters ofrecen una regla de claves de clasificación que marca objetos sin clasificar en el código fuente. Las bibliotecas estándar de idiomas exponen la misma capacidad, por ejemplo Python's json.dumps acepta un sort_keys=True argumento que produce resultados canónicos y ordenados.
Lo que agrega un clasificador basado en navegador es el caso rápido y sin configuración. Cuando tiene una masa de JSON de una respuesta API, una línea de registro o un mensaje Slack, y solo desea leerlo en un orden sensato en este momento, abrir una página y pegar es más rápido que conectar un formateador o colocarlo en un shell. Es la misma razón por la que existe un formateador de pegar y listo junto con los complementos del editor: la herramienta satisface la necesidad ad hoc que la canalización configurada no cubre.
¿mi JSON es privado?
Sí. El JSON se analiza, clasifica y vuelve a serializar completamente en su navegador mediante JavaScript. Nada se carga en un servidor, se registra ni se almacena en ningún lugar. Ese no es un detalle menor para JSON específicamente, porque JSON es donde viven los secretos: respuestas API que transportan tokens, archivos de configuración con cadenas de conexión, cargas útiles que contienen registros de clientes. Pegar todo eso en una herramienta que lo envía a un servidor es un riesgo real, y es exactamente el riesgo que esta herramienta debe evitar.
Puedes verificar el reclamo de la misma manera que lo haría yo. Abra la pestaña de red en su navegador 's herramientas de desarrollo y mírela mientras ordena; ninguna solicitud sale de la página. O desconectarse de Internet y seguir ordenando, porque una vez que la página se ha cargado, la herramienta funciona sin conexión alguna. El procesamiento del lado del cliente es el predeterminado para todo lo que construyo, y si le importa el argumento más amplio, el Guía de privacidad de datos presenta el caso en su totalidad.
Preguntas frecuentes
¿Qué significa ordenar las claves JSON?
La clasificación de claves JSON reordena los pares nombre-valor de un objeto en orden alfabético sin cambiar ningún valor. El objeto {"name":"toolz","author":"Liton"} se convierte en {"author":"Liton" "nombre":"toolz"}. Sólo cambia el orden de las claves, por lo que los datos que representa el documento permanecen exactamente iguales.
¿Las claves de ordenación cambian lo que significa mi json?
prohibido . En el estándar JSON, ECMA-404, un objeto es un conjunto desordenado de pares de nombre-valor, por lo que reordenar sus claves no cambia su significado. Cualquier analizador conforme lee las versiones ordenadas y no ordenadas como los mismos datos. El orden solo importa para la legibilidad humana y para producir diferencias estables.
¿También se ordenan los objetos anidados?
Sí, por defecto. La clasificación recursiva está activada, por lo que las claves de cada objeto dentro del documento se ordenan, en todos los niveles de anidación. Puede desactivar Recursion para ordenar solo las teclas de nivel superior y dejar los objetos anidados en su orden original.
¿Las matrices de ordenación de ordenadores?
No por defecto. Las matrices se ordenan por definición y reordenarlas puede cambiar el significado, por lo que la herramienta conserva el orden de la matriz. Existe una opción para ordenar matrices cuyos elementos son todos cadenas o todos los números cuando se quiere que se ordenen; las matrices que mezclan tipos o contienen objetos siempre se dejan como están.
¿Por qué ordenaría las claves JSON?
La razón más común son las diferencias estables: cuando cada archivo escribe sus claves en el mismo orden alfabético, los diferenciales de control de versiones resaltan solo los valores que cambiaron en lugar de las teclas que se movieron. La clasificación también hace que los archivos de configuración grandes y las respuestas de API sean mucho más fáciles de escanear y comparar a simple vista.
¿Cómo funciona la clasificación que no permite la insensibilidad de las mayúsculas y minúscula
Con la clasificación que no distingue entre mayúsculas y minúsculas, las claves se comparan como si estuvieran en minúsculas, por lo que el nombre, el nombre y el nombre se agrupan uno al lado del otro en lugar de separarse porque las letras mayúsculas se ordenan antes que las minúsculas en orden de caracteres en bruto. Desactívelo para ordenar estrictamente por punto de código de carácter.
¿Puedo minimizar el JSON ordenado?
Sí. Elija la salida minificada para obtener el JSON ordenado en una sola línea sin espacio en blanco adicional, que es el formulario más pequeño para el almacenamiento o el transporte. Para un archivo legible, elija Bonito salida con sangría de dos espacios, cuatro espacios o tabuladores.
¿Se subió mi json a alguna parte?
prohibido . El JSON se analiza y ordena por JavaScript en su navegador y nunca se transmite, registra ni se almacena. Puede verificar esto viendo la pestaña Red mientras se ordena o desconectando, la herramienta sigue funcionando sin conexión.
Escrito por Liton, creador de [Toolz.dev](/. Creo herramientas de desarrollo basadas en navegador y escribo sobre cómo trabajar con JSON, Laravel y la web.
