La tâche qui m'a appris à respecter l'aplatissement semblait ennuyeuse sur le ticket : " ; exporter l'objet paramètres vers une feuille de calcul afin que le client puisse le modifier." ; Les paramètres étaient un blob JSON profondément imbriqué d'une configuration de Laravel, à trois et quatre niveaux en profondeur par endroits, avec des tableaux de drapeaux de fonctionnalités mélangés. Une feuille de calcul comporte des colonnes, pas des arbres. J'avais besoin de chaque valeur de feuille comme d'une seule clé plate que le client pouvait voir dans une rangée, modifier et renvoyer, puis j'ai dû reconstruire la structure exacte imbriquée à partir de leurs modifications sans perdre un seul index de tableau. Cet aller-retour, imbriqué et est ce jeu JSON. Aplatisseur JSON est l'outil que j'ai construit pour ce travail, et ce guide explique comment il fonctionne et où il vous sauve.
tl;dr : Un flattener JSON convertit un objet imbriqué en un objet à un seul niveau dont les clés sont le chemin vers chaque valeur, donc
{"user":{"city":"Austin"}}se transforme{"user.city":"Austin"}. Les tableaux s'aplatissent avec leur index dans le chemin (roles.0). Unflatten l'inverse, reconstruisant les objets et tableaux imbriqués à partir de ces touches en pointillés. L'outil Toolz effectue les deux directions sans perte, préserve les objets et tableaux vides, prend en charge la notation de tableau de points ou de supports et un délimiteur personnalisé, et s'exécute entièrement côté client sans téléchargement ni inscription.
Je construis SaaS sur Laravel et React et j'expédie des plugins WordPress, donc JSON imbriqué est partout dans ma journée : fichiers de configuration, charges utiles API, catalogues de messages i18 n, magasins de fonctionnalités-drapeaux Les systèmes qui consomment ces charges utiles, cependant, veulent fréquemment des clés plates L'aplatissement est l'adaptateur entre une forme qui est naturelle pour les données structurées et une forme qui est naturelle pour les feuilles de calcul, les variables d'environnement et les magasins de clés en pointillés C'est une petite opération qui débloque tranquillement beaucoup de tâches autrement gênantes.
Qu'est-ce qu'un aplatineur JSON ?
Un flattener JSON convertit un objet JSON imbriqué en un objet à un seul niveau où chaque clé est le chemin complet de la racine à une valeur feuille La syntaxe du chemin n'est pas non plus arbitraire : RFC6901 définit JSON Pointer, la manière standard d'adresser une valeur à l'intérieur d'un document L'imbriqué {"user":{"name":"Ada","address":{"city":"Austin"}}} devient le plat {"user.name":"Ada","user.address.city":"Austin"}. Rien dans les valeurs ne change ; seul leur adressage le fait. Chaque feuille, aussi profonde soit-elle, reçoit une clé qui indique comment l'atteindre.
Les tableaux sont gérés de la même manière, l'index du tableau devenant un segment de chemin : {"roles":["admin","editor"]} s'aplatit pour {"roles.0":"admin","roles.1":"editor"}. L'index dans la clé est ce qui permet à l'opération inverse de reconstruire le tableau dans le bon ordre. Cette opération inverse, non aplatie, prend un objet plat de touches pointillées et reconstruit les objets et tableaux imbriqués, décidant à chaque étape si un segment de chemin nomme une propriété d'objet ou un index de tableau. Lorsque les éléments aplatis et aplatis utilisent la même notation de délimiteur et de tableau, ils sont des inverses exacts, et cet aller-retour sans perte est la propriété qui rend l'outil digne de confiance pour un travail réel plutôt que pour une commodité à sens unique.
Pourquoi j'aplatirais JSON en premier lieu ?
Parce que beaucoup de systèmes ne parlent que des paires clé-valeur plates, et un chemin en pointillés est le moyen standard de transporter la structure imbriquée à travers eux sans la perdre L'exemple le plus clair est une feuille de calcul Une feuille de calcul est une grille de colonnes, et il n'y a pas de colonne pour " ; la ville à l'intérieur de l'adresse à l'intérieur de l'utilisateur." ; Aplatir l'objet et user.address.city devient un seul en-tête de colonne sous lequel la valeur peut vivre, ce qui est exactement ce dont mon ticket de paramétrage-exportation avait besoin.
La même forme apparaît à de nombreux autres endroits. Variables environnementales et .env les fichiers sont plats, et les outils qui mappent la configuration à eux utilisent des chemins pointés ou soulignés Les bibliothèques d'internationalisation saisissent leurs chaînes de chemins pointés comme checkout.button.label. Les plates-formes de balises de fonctionnalité, les schémas d'événements d'analyse et de nombreux pipelines de journalisation veulent tous un niveau de clés, souvent pour pouvoir indexer ou interroger chaque champ indépendamment. Dans tous les cas, l'imbrication est réelle et significative, et l'aplatissement le préserve dans le chemin plutôt que de le supprimer. Lorsque la représentation plate a atteint son objectif, l'objet d'origine est reconstruit à plat. Si vous vous déplacez également spécifiquement entre JSON et les feuilles de calcul Convertisseur CSV vers JSON est le compagnon naturel de la partie tabulaire de ce voyage.
Comment les tableaux sont-ils gérés lors de l'aplatissement ?
Les tableaux sont la partie que les gens se trompent le plus souvent, il vaut donc la peine d'être précis Un élément de tableau est aplati en utilisant son index numérique comme segment de chemin, ce qui préserve l'ordre et permet de reconstruire exactement le tableau L'outil Toolz propose deux notations pour cet index, et ils codent les mêmes informations avec une syntaxe différente.
| Entrée | Notation dot | Notation du support |
|---|---|---|
{"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] |
Notation des points écrit roles.0, qui est compact et correspond au nombre de systèmes config et i18 n qui saisissent leurs valeurs La notation du support écrit roles[0][traduction], qui reflète la syntaxe d'accès JavaScript et le style de chemin utilisé par certains langages de requête Ni l'un ni l'autre n'est plus correct ; vous choisissez celui auquel le système à l'autre extrémité s'attend L'important est la cohérence : quelle que soit la notation avec laquelle vous aplatissez, utilisez la même pour ne pas aplatir, car c'est ainsi que l'outil connaît un segment numérique signifie " ; array index" ; plutôt que " ; une clé objet qui se trouve être un nombre." ; le flattener Toolz fait défaut pour la notation par points et vous permet de basculer entre crochets d'un clic.
Comment utiliser l'aplatisseur JSON ?
Le flux a deux directions et quelques options Commencez par choisir aplatir ou non avec la bascule en haut Aplatir prend JSON imbriqué et produit des touches pointillées ; unflatten prend les touches pointillées et reconstruit la structure imbriquée Load Sample remplit un exemple travaillé pour la direction dans laquelle vous vous trouvez, afin que vous puissiez voir la forme à la fois de l'entrée et de la sortie avant de coller vos propres données.
Coller votre JSON dans la boîte de saisie Pour aplatir, c'est un objet imbriqué ; pour unflatten, c'est un objet plat dont les touches sont des chemins en pointillés L'entrée doit être valide JSON, et si ce n'est pas le cas, l'outil signale le message parser' ; s et la position du problème au lieu de vous remettre une sortie vierge, donc une virgule traînante errante est rapide à trouver Définissez le style de la touche : le délimiteur se met par défaut en un point et peut être modifié lorsque vos touches contiennent déjà des points, et la notation du tableau bascule entre roles.0 et roles[0]. Gardez ces deux paramètres identiques sur un aplati et sa correspondance non aplatie afin que l'aller-retour s'aligne. Cliquez sur le bouton d'action, vérifiez le nombre de touches qui confirme le nombre de feuilles produites, copiez la sortie ou téléchargez-la sous forme de .json fichier. L'ensemble s'exécute à l'instant où vous cliquez, dans votre navigateur, sans rien envoyé nulle part.
L'aplatissement est-il sans perte et quels sont les cas de bord ?
Pour l'outil Toolz, oui, avec un cas de bord qui mérite d'être connu. Scalaires, null[TRADUCTION], les booléens, et les nombres survivent intacts La partie subtile est constituée de contenants vides : un objet vide {} ou un tableau vide [] est préservé comme une valeur de feuille plutôt que silencieusement lâché, donc une configuration qui repose sur une liste vide fait encore des allers-retours à exactement ce qu'il était Beaucoup d'aplatisseurs naïfs perdent des conteneurs vides, ce qui change tranquillement la signification d'un document, donc c'est un choix délibéré.
La seule limitation authentique concerne les clés qui contiennent déjà le délimiteur. Si vos données contiennent une clé objet contenant un point littéral, par exemple {"a.b":1}[TRADUCTION], et vous vous aplatissez avec un délimiteur de points, le chemin devient ambigu : unflatten ne peut pas dire si a.b était une clé ou un imbriqué a à ce moment- b. Le correctif est de changer le délimiteur pour un caractère qui n'apparaît pas dans vos clés, comme une barre oblique ou un tuyau, et d'utiliser ce même délimiteur pour les deux directions C'est la même classe de problème d'échappement que vous voyez quand Les délimiteurs CSV entrent en collision avec les données[TRADUCTION], et la même solution s'applique : choisissez un séparateur que vos valeurs ne contiennent pas En dehors de ce cas, un aplatissement suivi d'un aplati avec des paramètres correspondants reproduit exactement le document original, tableaux et conteneurs vides inclus.
Quelle est la différence entre l'aplatissement et la conversion à un autre format ?
L'aplatissement n'est pas une conversion de format ; c'est une restructuration au sein de JSON La sortie d'un aplati est toujours JSON, juste avec un seul niveau de touches en pointillés au lieu d'imbriquer C'est différent des convertisseurs qui transforment JSON en une sérialisation véritablement différente, et savoir de laquelle vous avez besoin sauve une étape.
Si vous souhaitez les mêmes données exprimées en YAML pour un fichier de configuration, le Convertisseur JSON en YAML est l'outil, parce qu'il change la syntaxe plutôt que la forme Si vous voulez une interface TypeScript décrivant la structure pour que votre frontal sache ce qu'il gère, le Convertisseur JSON vers TypeScript infère cela à partir d'un échantillon Si vous souhaitez un contrat formel pour la validation, le Générateur de schéma JSON dérive un schéma JSON d'un exemple L'aplatissement se trouve à côté de ceux-ci plutôt que de les remplacer : vous aplatissez lorsqu'un système en aval veut un niveau de clés, et vous convertissez lorsqu'un système veut un langage différent Je fais fréquemment les deux en séquence, aplatissant une charge utile pour l'éditer sous forme de colonnes puis, séparément, générant des types pour la version imbriquée que je remets à React Pour la jolie impression ou la validation du JSON à n'importe quel point de cette chaîne, le Formateur JSON est l'utilitaire que je garde ouvert dans l'onglet suivant.
Comment unflatten décide-t-il entre un tableau et un objet ?
C'est le mécanisme qui fait fonctionner l'aller-retour, et le comprendre explique à la fois les valeurs par défaut de l'outil' ; et son seul bord tranchant. Lorsqu'il n'est pas aplati, il lit une clé comme user.roles.0« , il le divise en segments » user, roles, et 0(en), puis les fait marcher en construisant la structure au fur et à mesure. A chaque étape, il regarde le segment suivant pour décider quel genre de conteneur créer Si le segment suivant est un entier non négatif, il fait un tableau ; si c'est autre chose, il fait un objet Donc roles.0 indique à l'outil que roles devrait être un tableau dont le premier élément est la valeur, tandis que address.city dit ça address devrait être un objet avec un city propriété.
Cette règle unique, " ; segment entier signifie index de tableau, " ; est la raison pour laquelle un aplati et un aplati avec des paramètres correspondants reproduisent exactement les tableaux C'est aussi la raison pour laquelle la notation de tableau que vous choisissez doit être cohérente En notation de point l'index de tableau et une clé d'objet sont tous deux juste du texte entre les points, donc l'outil s'appuie entièrement sur le test des entiers En notation de parenthèse le [0] la syntaxe rend l'intention explicite avant même que la division ne se produise. L'un ou l'autre fonctionne, mais les mélanger, les aplatir avec des crochets et les aplatir avec des points, brise le signal dont dépend l'outil.
Voici le tranchant qui découle de la règle : un objet dont les touches sont véritablement les cordes "0", "1", "2" est indiscernable, une fois aplati, d'un tableau Les deux produisent les clés 0, 1, 2« , et unflatten les reconstruira en tableau car c'est le cas extrêmement courant. Si vous avez vraiment besoin d'un objet avec des clés de chaîne numériques pour survivre à l'aller-retour, c'est la seule situation où l'aplatissement et l'aplatissement ne vous rendront pas le type exact, et vous feriez mieux de garder cet objet imbriqué ou d'utiliser un système de clés non numériques. Au cours des années à faire, j'ai frappé ce cas exactement deux fois, les deux fois dans des données qui ont sans doute été mal modélisées pour commencer, donc la valeur par défaut est le bon commerce pour presque tout le monde. C'est le même genre de décision pragmatique derrière le maintien de nombres avec des zéros en tête comme chaînes dans le Convertisseur CSV vers JSON: l'outil optimise ce que les données signifient presque toujours et documente la rare exception plutôt que de rendre le chemin commun gênant.
Mon JSON peut-il coller en toute sécurité dans cet outil ?
Oui, et c'est architectural plutôt qu'une promesse Parsing, aplatissement, aplatissement, et sérialisation tous s'exécutent en tant que JavaScript à l'intérieur de votre propre onglet de navigateur Il n'y a pas de téléchargement, pas de serveur aller-retour, et rien n'est enregistré ou stocké Ouvrez votre navigateur' ; s onglet réseau et cliquez sur le bouton d'action : aucune requête ne s'éteint Une fois la page chargée vous pouvez vous déconnecter d'internet et il continue de fonctionner, car il n'y avait jamais de serveur dans la boucle pour commencer.
Cela compte plus qu'il n'y paraît, car les charges utiles JSON sont exactement le genre de chose qui transporte des secrets : jetons API dans une configuration, données personnelles dans une réponse API, identifiants internes dans une blob de paramètres Un flattener qui téléchargeait votre objet sur un serveur transformerait une charge utile privée en quelqu'un d'autre' ; s ligne de journal Le traitement côté client supprime entièrement le risque, c'est pourquoi c'est la valeur par défaut sur chaque outil sur Toolz.dev. Si vous voulez le raisonnement complet, je l'ai exposé dans guide de confidentialité des données pour les outils en ligne« Et le kit plus large que j'utilise pour ce genre de travail est dans mon » Guide d'outils pour les développeurs Web.
Questions fréquentes
Qu'est-ce que ça veut dire d'aplatir JSON ?
Aplatissement JSON convertit un objet imbriqué en un objet à un seul niveau dont les clés sont le chemin vers chaque valeur L'imbriqué {"user":{"city":"Austin"}} devient le plat {"user.city":"Austin"}. Chaque valeur de feuille obtient une clé en pointillés, et aucun imbrication ne reste dans la sortie Unflatten inverse le processus et reconstruit la structure imbriquée.
Comment les tableaux sont-ils gérés lors de l'aplatissement ?
Les éléments du réseau sont aplatis en utilisant leur index comme segment de chemin. {"roles":["admin","editor"]} se transforme {"roles.0":"admin","roles.1":"editor"} en notation par points, ou {"roles[0]":"admin","roles[1]":"editor"} en notation entre parenthèses L'index préserve l'ordre afin que le tableau puisse être reconstruit exactement lorsque vous ne vous aplanissez pas.
Puis-je remettre les touches pointillées non aplaties dans JSON imbriqué ? Oui. Passez en mode non aplati et collez un objet plat dont les touches sont des chemins en pointillés L'outil reconstruit les objets et tableaux imbriqués, en décidant tableau contre objet selon que chaque segment de chemin est un index entier Aplati et non aplati sont des inverses exacts lorsque le délimiteur et la notation du tableau correspondent.
Quelle est la différence entre la notation par points et par crochets ?
Les deux codent le même index de tableau ; seule la syntaxe diffère. La notation par points écrit items.0.id[traduction], qui est compact et courant dans les touches config et i18 n. Écritures de notation de support items[0].id(en anglais), qui correspond à la syntaxe d'accès JavaScript et à certains langages de requête Choisissez celui que votre système cible attend, et utilisez le même pour les deux directions.
L'aplatissement perd-il des données ? Non. Les scalaires, les nuls, les booléens et même les objets vides et les tableaux vides sont conservés sous forme de valeurs feuilles, donc le fait de dégraisser le résultat reproduit le document original. La seule chose à surveiller, ce sont les touches qui contiennent déjà votre délimiteur, c'est pourquoi le séparateur est configurable.
Pourquoi j'aplatirais JSON ? L'aplatissement adapte les données imbriquées aux systèmes qui s'attendent à un niveau de clés : colonnes de feuilles de calcul, variables d'environnement, clés de traduction en pointillés, magasins de balises de fonctionnalités et de nombreux pipelines d'analyse et de journalisation. Le chemin en pointillés transporte la structure d'origine à travers un format plat afin que rien ne soit perdu.
Que se passe-t-il si une clé contient déjà un point ? Un point littéral à l'intérieur d'une clé est ambigu avec le séparateur de chemin, de sorte que l'aller-retour peut le diviser au mauvais endroit Changez le délimiteur en un caractère qui n'apparaît pas dans vos clés, comme une barre oblique ou un tuyau, et utilisez ce même délimiteur à la fois pour l'aplatir et l'aplatir.
Mon JSON est-il téléchargé quelque part ? Non. L'analyse et la transformation s'exécutent en JavaScript dans votre navigateur Rien n'est transmis, enregistré ou stocké Vous pouvez le confirmer en regardant l'onglet réseau pendant l'aplatissement, ou en se déconnectant, puisque l'outil continue de fonctionner sans connexion.
