Convertir JSON en YAML

C’est la seule conversion de ce groupe de pages où la réponse à « qu’est-ce que cela me coûte » est véritablement rien. YAML 1.2, publié en 2009 et la version que la spécification porte depuis, définit JSON comme un sous-ensemble : tout document JSON valide est déjà du YAML valide. La conversion re-sérialise le même arbre dans un autre style.

Cela rend le reste de cette page inhabituel. Il n’y a pas d’étape destructive à signaler, pas d’aplatissement, pas de type qu’il faille approximer. Ce qu’il y a à la place est un ensemble de questions sur la manière dont le résultat sera lu, et il se trouve que ces questions comptent plus que ne le ferait une perte de données.

L’auteur suit YAML 1.2, selon lequel no, yes, on et off sont des chaînes ordinaires. Ainsi, une valeur JSON de « no » est écrite comme un no nu, sans guillemets, et relire ce document avec un parseur 1.2 rend la chaîne dont on était parti. C’est un comportement correct et l’aller-retour est parfait.

YAML 1.1 n’est pas d’accord. Il résout ces mêmes mots en booléens, et PyYAML — qui est ce qu’utilisent Ansible, une grande partie de l’outillage Python et d’innombrables scripts internes — est un lecteur 1.1. Donc un code pays de deux lettres, un champ « réponse », une colonne intitulée consent : la valeur entre comme la chaîne no et sort comme false. Si un outil Python est en aval, mettez ces valeurs entre guillemets à la main après la conversion. C’est une petite édition et c’est la manière la plus probable dont cette conversion produira un fichier qui a l’air juste mais se comporte faux.

La mise entre guillemets est décidée valeur par valeur, et seulement là où la forme nue serait lue comme autre chose. La chaîne « 1.0 » est mise entre guillemets, parce que sans cela c’est un nombre. La chaîne « null » est mise entre guillemets, parce que sans cela c’est la valeur null. Une chaîne commençant par un dièse est mise entre guillemets, parce qu’un dièse nu commence un commentaire, et une chaîne avec des espaces en tête ou en queue est mise entre guillemets, parce que YAML les supprimerait sinon.

La règle est cohérente et c’est une règle 1.2, ce qui est précisément le propos de la section précédente. Tout ce que l’auteur met entre guillemets changerait de sens sous YAML 1.2 ; les mots qu’il laisse nus sont ceux qui ne changent de sens que sous 1.1. Une chaîne en forme de date comme 2024-01-01 est laissée nue pour la même raison, et un lecteur 1.1 la transforme en horodatage.

Une chaîne JSON ne peut pas contenir de saut de ligne littéral, donc un script shell, un certificat ou une instruction SQL embarqués dans un manifeste JSON tiennent sur une seule ligne énorme avec des backslash-n là où les coupures devraient être. Relire un changement dessus n’est pas vraiment possible.

L’auteur YAML émet ces valeurs sous forme de scalaires bloc : un caractère pipe, puis le texte sur ses propres lignes indentées avec les sauts de ligne là où ils se trouvent. Un script entrypoint de douze lignes devient douze lignes dans le fichier. Pour quiconque dont la raison de convertir est que le manifeste doit être relu par une personne, c’est en général la plus grosse amélioration de la sortie, et c’est invisible jusqu’à ce que le fichier en contienne un.

Un tableau JSON d’objets se convertit dans la liste préfixée par des tirets que chaque exemple Kubernetes et GitHub Actions est écrite ainsi : un tiret, puis la première clé sur la même ligne et le reste en retrait en dessous. Containers, steps, volumes, jobs — tous arrivent dans la forme que montre la documentation.

Cela compte pour la relecture plutôt que pour l’exactitude, et c’est la relecture qui est la raison d’être du fichier. Un reviewer qui parcourt une liste de six étapes de déploiement en YAML voit les frontières entre elles sans compter les accolades, ce qui est la raison pour laquelle l’écosystème a choisi ce format malgré ses pièges d’indentation.

JSON ne transporte pas de commentaires, ce qui découle de la grammaire dans la RFC 8259 plutôt que d’un accident de parseurs — il n’y a aucune production pour un commentaire, donc un parseur conforme n’a rien à accepter. YAML les accepte partout où une ligne peut commencer par un dièse. Convertir un manifeste généré en YAML n’est très souvent même pas une affaire de syntaxe — c’est faire du fichier un endroit où la raison d’une valeur peut vivre à côté de la valeur.

Rien dans la sortie ne porte de commentaires, parce que l’entrée n’en avait pas à donner. Les ajouter est la première édition qui vaut la peine, et les plus utiles ne sont jamais des descriptions de ce qu’est un champ. Écrivez pourquoi le nombre de répliques est de trois, à quel autre dépôt le tag d’image doit correspondre, et ce qui casse si l’on baisse le délai.

YAML a des ancres et des alias, qui permettent de définir un bloc une fois et de le référencer à trois endroits, et il a plusieurs documents dans un seul fichier séparés par trois tirets. Les deux sont largement utilisés — les fichiers compose et les bundles Kubernetes s’appuient dessus — et aucun des deux ne peut sortir d’une source JSON, parce que JSON n’a aucun moyen d’exprimer l’un ou l’autre.

Donc le fichier converti est correct et plat : tout ce qui est répété dans le JSON est répété dans le YAML. Facteur de répétition en dehors avec une ancre est une édition manuelle, et qui vaut la peine seulement là où la répétition est réelle. Un bundle de manifestes séparés concaténés en un seul tableau JSON est l’autre cas, et là le bon résultat est plusieurs documents dans un seul fichier, ce qui est à nouveau une édition plutôt qu’une conversion.

L’auteur préserve l’ordre dans lequel les clés sont arrivées, donc apiVersion, kind et metadata restent là où ils étaient plutôt que d’être triés. Ni JSON ni YAML ne définit l’ordre des mappings comme significatif, et de nombreux outils réordonnent librement, mais un manifeste dont les clés ont été alphabétisées est plus difficile à lire et produit un gros diff sans raison.

Cela vaut la peine d’être su quand on compare la sortie avec un fichier déjà dans le dépôt. Si les deux ne diffèrent que par l’ordre, la différence vient de ce qui a produit le JSON, pas de cette conversion — relire une ressource depuis un cluster, par exemple, rend les champs dans l’ordre du serveur d’API plutôt que dans celui où vous les aviez écrits.

La vérification qui coûte le moins est le dry-run de l’outil lui-même : kubectl apply avec --dry-run=client, docker compose config, ou le linter de workflow pour un fichier Actions. Chacun analyse le document et rapporte la forme qu’il a trouvée, ce qui attrape une clé mal placée bien plus vite qu’une lecture du fichier.

La vérification qui attrape le problème de mise entre guillemets est différente et doit être faite exprès : chercher dans le fichier converti les yes, no, on, off nus et toute date sans guillemets, et décider pour chacun si un lecteur YAML 1.1 va jamais le voir. Cela prend une minute et c’est la seule partie de cette conversion sur laquelle un parseur ne vous alertera pas.

La conversion tourne dans cet onglet. Le JSON est analysé par le parseur du navigateur et le YAML est écrit par une bibliothèque chargée à la demande, donc aucune requête ne transporte le document, il n’y a pas d’inscription ni de limite journalière, et le niveau gratuit accepte jusqu’à 100 Mo — bien plus que n’importe quel manifeste.

Pour ce lectorat, c’est une préoccupation pratique plutôt qu’abstraite. Un manifeste tiré d’un cluster en cours d’exécution contient des noms d’hôtes internes, des chemins de registres, des noms de comptes de service et la forme de l’infrastructure, et un certain nombre d’organisations traitent le fait de coller cela dans un convertisseur web public comme un incident. Ici il n’y a rien à coller et rien à envoyer.