La tarea que me enseñó a respetar el aplanamiento parecía aburrida en el ticket: " exportar el objeto de configuración a una hoja de cálculo para que el cliente pueda editarlo." La configuración era una mancha JSON profundamente anidada a partir de una configuración de Laravel, de tres y cuatro niveles de profundidad en algunos lugares, con matrices de indicadores de características mezcladas. Una hoja de cálculo tiene columnas, no árboles. Necesitaba cada valor de hoja como una única clave plana que el cliente podía ver en una fila, editar y devolver, y luego necesitaba reconstruir la estructura anidada exacta a partir de sus ediciones sin perder un solo índice de matriz. Ese viaje de ida y vuelta, anidado a plano y de regreso a anidado, es lo que hace un aplanador JSON, y conseguirlo sin pérdidas es todo el juego. La herramienta Aplanador JSON es la herramienta que construí para ese trabajo y esta guía explica cómo funciona y dónde te salva.
TL;Dr: Un aplanador JSON convierte un objeto anidado en un objeto de un solo nivel cuyas claves son la ruta a cada valor, por lo tanto
{"user":{"city":"Austin"}}se convierte en{"user.city":"Austin"}. Las matrices se aplanan con su índice en el camino (roles.0). Unflatten lo invierte, reconstruyendo los objetos y matrices anidados a partir de esas claves punteadas. La herramienta Toolz realiza ambas direcciones sin pérdidas, conserva objetos y matrices vacíos, admite notación de matriz de puntos o corchetes y un delimitador personalizado, y se ejecuta completamente en el lado del cliente sin carga ni registro.
Construyo SaaS en Laravel y React y envío complementos de WordPress, por lo que JSON anidado está en todas partes de mi época: archivos de configuración, cargas útiles API, catálogos de mensajes i18n, almacenes de bandera de funciones. Sin embargo, los sistemas que consumen esas cargas útiles con frecuencia quieren claves planas. El aplanamiento es el adaptador entre una forma natural para datos estructurados y una forma natural para hojas de cálculo, variables de entorno y almacenes de claves punteadas. Es una pequeña operación que desbloquea silenciosamente muchas tareas que de otro modo serían molestas.
¿qué es un aplanador JSON?
Un aplanador JSON convierte un objeto JSON anidado en un objeto de un solo nivel donde cada clave es la ruta completa desde la raíz hasta un valor hoja. La sintaxis de la ruta tampoco es arbitraria: RFC 6901 define JSON Pointer, la forma estándar de abordar un valor dentro de un documento. El anidado {"user":{"name":"Ada","address":{"city":"Austin"}}} se convierte en el piso {"user.name":"Ada","user.address.city":"Austin"}. Nada sobre los valores cambia; sólo lo hace su dirección. Cada hoja, por profunda que sea, recibe una clave que explica cómo alcanzarla.
Las matrices se manejan de la misma manera, convirtiéndose el índice de la matriz en un segmento de ruta: {"roles":["admin","editor"]} aplana a {"roles.0":"admin","roles.1":"editor"}. El índice de la clave es lo que permite que la operación inversa reconstruya la matriz en el orden correcto. Esa operación inversa, desaplanar, toma un objeto plano de claves punteadas y reconstruye los objetos y matrices anidados, decidiendo en cada paso si un segmento de ruta nombra una propiedad de objeto o un índice de matriz. Cuando aplanar y desaplanar usan el mismo delimitador y notación de matriz, son inversos exactos, y ese viaje de ida y vuelta sin pérdidas es la propiedad que hace que la herramienta sea confiable para un trabajo real en lugar de una conveniencia unidireccional.
¿por qué aplanaría JSON en primer lugar?
Porque muchos sistemas solo hablan pares clave-valor planos, y una ruta punteada es la forma estándar de transportar una estructura anidada a través de ellos sin perderla. El ejemplo más claro es una hoja de cálculo. Una hoja de cálculo es una cuadrícula de columnas y no hay columna para " la ciudad dentro de la dirección dentro del usuario." Aplanar el objeto y user.address.city se convierte en un encabezado de una sola columna en el que el valor puede vivir, que es exactamente lo que necesitaba mi ticket de exportación de configuración.
La misma forma aparece en muchos otros lugares. Variables ambientales y .env los archivos son planos y las herramientas que les asignan configuración utilizan rutas con puntos o subrayadas. Las bibliotecas de internacionalización codifican sus cadenas con rutas con puntos como checkout.button.label. Las plataformas de bandera de características, los esquemas de eventos de análisis y muchos canales de registro quieren un nivel de claves, a menudo para que puedan indexar o consultar cada campo de forma independiente. En todos los casos, el anidamiento es real y significativo, y el aplanamiento lo preserva en la ruta en lugar de descartarlo. Cuando la representación plana ha cumplido su propósito, unflatten reconstruye el objeto original. Si también se mueve específicamente entre JSON y hojas de cálculo, el Convertidor CSV a JSON es el compañero natural del tramo tabular de ese viaje.
¿cómo se manejan las matrices al aplanarlas?
Las matrices son la parte en la que la gente se equivoca con mayor frecuencia, por lo que vale la pena ser preciso. Un elemento de matriz se aplana utilizando su índice numérico como segmento de ruta, lo que preserva el orden y permite reconstruir la matriz exactamente. La herramienta Toolz ofrece dos notaciones para ese índice y codifican la misma información con una sintaxis diferente.
| Entrada | Notación de puntos | Notación de corchetes |
|---|---|---|
{"roles":["admin","editor"]} |
roles.0, roles.1 |
roles[0], roles[1] |
{"items":[{"id":1}]} |
items.0.id |
items[0].id |
{"matrix":[[1,2]]} |
matrix.0.0 |
matrix[0][0] |
Escribe notación de puntos roles.0, que es compacto y coincide con cuántos sistemas config e i18n codifican sus valores. Escribe notación de corchetes roles[0], que refleja la sintaxis de acceso a JavaScript y el estilo de ruta que utilizan algunos lenguajes de consulta. Ninguno de los dos es más correcto; eliges el que espera el sistema en el otro extremo. Lo importante es la coherencia: sea cual sea la notación con la que aplanes, usa la misma para desaplanar, porque así es como la herramienta conoce un segmento numérico que significa "array index" en lugar de " una clave de objeto que resulta ser un número." El aplanador de Toolz tiene por defecto la notación de puntos y le permite cambiar al corchete con un clic.
¿cómo uso el aplanador JSON?
El flujo tiene dos direcciones y un par de opciones. Comience eligiendo aplanar o desaplanar con el interruptor en la parte superior. Aplanar toma JSON anidado y produce claves punteadas; desaplanar toma claves punteadas y reconstruye la estructura anidada. Load Sample completa un ejemplo trabajado para cualquier dirección en la que se encuentre, para que pueda ver la forma tanto de la entrada como de la salida antes de pegar sus propios datos.
Pegue su JSON en el cuadro de entrada. Para aplanar, es decir, un objeto anidado; para desaplanar, es un objeto plano cuyas claves son rutas de puntos. La entrada tiene que ser JSON válida y, si no lo es, la herramienta informa el mensaje del analizador 's y la posición del problema en lugar de entregarle una salida en blanco, por lo que se puede encontrar rápidamente una coma final perdida. Establezca el estilo de clave: el delimitador tiene por defecto un punto y se puede cambiar cuando sus claves ya contienen puntos y la notación de matriz cambia entre ellas roles.0 y roles[0]. Mantenga esas dos configuraciones idénticas en un aplanamiento y su coincidencia se desaplane para que el viaje de ida y vuelta se alinee. Haga clic en el botón de acción, verifique el recuento de claves que confirma cuántas hojas se produjeron y copie la salida o descárguela como .json archivo. Todo se ejecuta en el instante en que hace clic, en su navegador, sin que se envíe nada a ninguna parte.
El aplanamiento no tiene pérdidas, ¿y cuáles son los casos de borde?
Para la herramienta Toolz, sí, con un caso de borde que vale la pena conocer. Escalares, null, booleanos y números sobreviven intactos. La parte sutil son contenedores vacíos: un objeto vacío {} o una matriz vacía [] se conserva como un valor de hoja en lugar de eliminarse silenciosamente, por lo que una configuración que se basa en una lista vacía todavía da vueltas y vueltas a lo que era exactamente. Muchos aplanadores ingenuos pierden contenedores vacíos, lo que cambia silenciosamente el significado de un documento, por lo que se trata de una elección deliberada.
La única limitación genuina son las claves que ya contienen el delimitador. Si sus datos tienen una clave de objeto con un punto literal, como {"a.b":1}, y si aplanas con un delimitador de puntos, el camino se vuelve ambiguo: no aplanar no puede decir si a.b era una llave o un anidado a de entonces b. La solución es cambiar el delimitador a un carácter que no aparece en sus claves, como una barra o una tubería, y usar ese mismo delimitador en ambas direcciones. Es la misma clase de problema de escape que ves cuando Los delimitadores CSV chocan con los datos, y se aplica la misma solución: elija un separador que sus valores no contengan. Fuera de ese caso, un aplanamiento seguido de un desaplanamiento con configuraciones coincidentes reproduce exactamente el documento original, incluidas las matrices y los contenedores vacíos.
¿cuál es la diferencia entre aplanar y convertir a otro formato?
El aplanamiento no es una conversión de formato; es una reestructuración dentro de JSON. La salida de un aplanamiento sigue siendo JSON, solo que con un solo nivel de claves punteadas en lugar de anidar. Eso es diferente de los convertidores que convierten JSON en una serialización genuinamente diferente, y saber cuál necesitas guarda un paso.
Si desea expresar los mismos datos que YAML para un archivo de configuración, el Convertidor JSON a YAML es la herramienta porque cambia la sintaxis en lugar de la forma. Si desea una interfaz TypeScript que describa la estructura para que su interfaz sepa lo que está manejando, el Convertidor JSON a TypeScript infiere eso de una muestra. Si desea un contrato formal para su validación, el Generador de esquemas JSON deriva un esquema JSON de un ejemplo. El aplanamiento se ubica junto a estos en lugar de reemplazarlos: aplanas cuando un sistema descendente quiere un nivel de claves y conviertes cuando un sistema quiere un lenguaje diferente. Con frecuencia hago ambas cosas en secuencia, aplanando una carga útil para editarla como columnas y luego, por separado, generando tipos para la versión anidada que entrego a React. Para imprimir o validar bastante el JSON en cualquier punto de esa cadena, el Formateador JSON es la utilidad que mantengo abierta en la siguiente pestaña.
¿cómo decide desaplanar entre una matriz y un objeto?
Este es el mecanismo que hace que el viaje de ida y vuelta funcione, y comprenderlo explica tanto los valores predeterminados de la herramienta 's como su único borde afilado. Cuando desaplanar lee una clave como user.roles.0, lo divide en segmentos user, rolesy 0, luego los acompaña construyendo la estructura a medida que avanza. En cada paso, mira el siguiente segmento para decidir qué tipo de contenedor crear. Si el siguiente segmento es un número entero no negativo, forma una matriz; si es cualquier otra cosa, crea un objeto. Entonces roles.0 le dice eso a la herramienta roles debe ser una matriz cuyo primer elemento sea el valor, mientras address.city le dice eso address debe ser un objeto con a city propiedad.
Esa única regla, "segmento entero significa índice de matriz," es por eso que aplanar y desaplanar con configuraciones coincidentes reproducen matrices exactamente. También es la razón por la que la notación de matriz que elija debe ser consistente. En notación de puntos, el índice de matriz y una clave de objeto son solo texto entre puntos, por lo que la herramienta se basa completamente en la prueba de números enteros. En notación entre corchetes el [0] la sintaxis hace explícita la intención incluso antes de que se produzca la división. Cualquiera de los dos funciona, pero mezclarlos, aplanarlos con corchetes y desaplanarlos con puntos, rompe la señal de la que depende la herramienta.
Aquí está el filo que se deriva de la regla: un objeto cuyas claves realmente son las cuerdas "0", "1", "2" es indistinguible, una vez aplanado, de una matriz. Ambos producen las claves 0, 1, 2, y desaplanarlos los reconstruirá como una matriz porque ese es el caso abrumadoramente común. Si realmente necesitas un objeto con claves de cadena numéricas para sobrevivir al viaje de ida y vuelta, esa es la única situación en la que aplanar y desaplanar no te devolverá el tipo exacto, y es mejor que mantengas ese objeto anidado o usando un esquema de clave no numérico. En años de hacer esto, he acertado en ese caso exactamente dos veces, ambas veces en datos que posiblemente fueron modelados incorrectamente para empezar, por lo que el valor predeterminado es el intercambio correcto para casi todos. Es el mismo tipo de decisión pragmática detrás de mantener números con ceros a la izquierda como cadenas en el Convertidor CSV a JSON: la herramienta optimiza lo que casi siempre significan los datos y documenta la rara excepción en lugar de hacer que el camino común sea incómodo.
¿es seguro pegar mi JSON en esta herramienta?
Sí, y es más arquitectónico que una promesa. Analizar, aplanar, desaplanar y serializar se ejecutan como JavaScript dentro de la pestaña de su propio navegador. No hay carga, ni servidor de ida y vuelta, y no hay nada registrado ni almacenado. Abra la pestaña de red de su navegador ' y haga clic en el botón de acción: no se cierra ninguna solicitud. Una vez que la página se haya cargado, puede desconectarse de Internet y sigue funcionando, porque, para empezar, nunca hubo un servidor en el bucle.
Esto importa más de lo que parece, porque las cargas útiles JSON son exactamente el tipo de cosas que contienen secretos: tokens API en una configuración, datos personales en una respuesta API, identificadores internos en un bloque de configuración. Un aplanador que cargara su objeto en un servidor convertiría una carga útil privada en otra persona 's línea de registro. El procesamiento del lado del cliente elimina el riesgo por completo, razón por la cual es el valor predeterminado en todas las herramientas en Toolz.dev. Si desea el razonamiento completo, lo expongo en el guía de privacidad de datos para herramientas en línea, y el kit más amplio que uso para este tipo de trabajo está en mi Guía del kit de herramientas para desarrolladores web.
Preguntas frecuentes
¿qué significa aplanar JSON?
Aplanar JSON convierte un objeto anidado en un objeto de un solo nivel cuyas claves son la ruta a cada valor. El anidado {"user":{"city":"Austin"}} se convierte en el piso {"user.city":"Austin"}. Cada valor de hoja recibe una clave punteada y no queda ningún nido en la salida. Unflatten invierte el proceso y reconstruye la estructura anidada.
¿cómo se manejan las matrices al aplanarlas?
Los elementos de la matriz se aplanan utilizando su índice como segmento de ruta. {"roles":["admin","editor"]} se convierte en {"roles.0":"admin","roles.1":"editor"} en notación de puntos, o {"roles[0]":"admin","roles[1]":"editor"} en notación entre corchetes. El índice conserva el orden para que la matriz pueda reconstruirse exactamente cuando se desaplana.
¿puedo desaplanar las teclas punteadas nuevamente en JSON anidado? Sí. Cambie al modo desaplanar y pegue un objeto plano cuyas claves sean rutas punteadas. La herramienta reconstruye los objetos y matrices anidados, decidiendo matriz versus objeto por si cada segmento de ruta es un índice entero. Aplanar y desaplanar son inversos exactos cuando el delimitador y la notación de matriz coinciden.
¿cuál es la diferencia entre la notación de matriz de puntos y de corchetes?
Ambos codifican el mismo índice de matriz; sólo difiere la sintaxis. Escribe notación de puntos items.0.id, que es compacto y común en las claves config e i18n. Escribe notación de corchetes items[0].id, que coincide con la sintaxis de acceso a JavaScript y algunos lenguajes de consulta. Elija lo que espere su sistema de destino y use el mismo para ambas direcciones.
¿el aplanamiento pierde algún dato? No. Los escalares, los nulos, los booleanos e incluso los objetos vacíos y las matrices vacías se conservan como valores de hoja, por lo que desaplanar el resultado reproduce el documento original. Lo único que hay que tener en cuenta son las teclas que ya contienen su delimitador, razón por la cual el separador es configurable.
¿por qué aplanaría JSON? El aplanamiento adapta datos anidados a sistemas que esperan un nivel de claves: columnas de hojas de cálculo, variables de entorno, claves de traducción punteadas, almacenes de banderas de características y muchos canales de análisis y registro. La ruta punteada lleva la estructura original a través de un formato plano para que no se pierda nada.
¿Qué sucede si una clave ya contiene un punto? Un punto literal dentro de una tecla es ambiguo con el separador de ruta, por lo que el viaje de ida y vuelta puede dividirlo en el lugar equivocado. Cambie el delimitador por un carácter que no aparezca en sus teclas, como una barra o una tubería, y use el mismo delimitador tanto para aplanar como para desaplanar.
¿Se subió mi json a alguna parte? No. El análisis y la transformación se ejecutan como JavaScript en su navegador. No se transmite, registra ni almacena nada. Puede confirmar esto observando la pestaña de red mientras se aplana o desconectándose, ya que la herramienta sigue funcionando sin conexión.
