Convertir YAML en JSON

C’est la seule de ce groupe de pages où la réponse à « qu’est-ce que cela me coûte » est essentiellement 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 lit donc l’arbre du YAML et le re-sérialise dans la syntaxe JSON, sans rien écarter dans le cas général.

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 cas où YAML va plus loin que JSON, et où la conversion doit soit résoudre soit abandonner ce qu’elle trouve. Ces cas sont peu nombreux, mais chacun a une histoire.

YAML permet de définir un bloc une fois sous une étiquette (&id) et de le référencer à plusieurs endroits (*id). Le JSON n’a aucune notion d’alias, donc chaque référence est résolue en une copie complète du bloc. Le résultat est correct et volumineux : un manifeste de cinq jobs qui partagent la même configuration apparaît avec cette configuration répétée cinq fois.

Pour la plupart des fichiers de configuration, c’est indolore parce que les sections partagées sont petites. Pour un fichier où la même structure lourde est référencée vingt fois, la sortie peut être vingt fois plus longue que la source, et la compression en aval ne récupère qu’une partie. Si la taille compte, déplier les ancres à la main en YAML avant la conversion est l’édition qui vaut la peine.

Le YAML autorise un commentaire n’importe où sur une ligne, après un dièse, et un fichier produit par une personne en est en général plein. Le JSON n’a aucune production grammaticale pour un commentaire — la RFC 8259 le précise — donc la conversion les supprime sans trace. C’est l’unique cas où cette page cause une perte, et c’est le seul cas où l’opération est vraiment destructive.

L’habitude qui compense est d’extraire les commentaires dans un fichier à part avant la conversion, ou de les intégrer dans des clés descriptives que le format cible comprend. Un manifeste Kubernetes converti en JSON pour un client API ne perd rien qui pilote le comportement, parce que les commentaires n’en pilotaient aucun. Le commentaire « pourquoi trois répliques » est précieux et doit vivre ailleurs, sous la forme d’une note de version ou d’un ticket.

YAML admet plusieurs documents dans un seul fichier, séparés par trois tirets (---). Le JSON a un document par fichier, donc la conversion sort le premier et ignore les suivants, en avertissant. Pour la majorité des cas, c’est sans importance, parce que la grande majorité des fichiers YAML en circulation portent un seul document.

Quelques écosystèmes utilisent le multi-document délibérément. Les bundles Kubernetes concatènent des manifests séparés par ---, et la même convention apparaît dans certains flux d’outillage. Si le fichier en est un, concaténez-le en autant de fichiers qu’il a de documents et convertissez-les un par un, ou prenez un outil qui sait séparer avant la conversion. La sortie n’est pas silencieuse : un avertissement est attaché au résultat quand des documents ont été écartés.

Le YAML 1.2 distingue null, bool, int, float et string, avec un petit nombre de représentations qui prêtent à confusion : yes, no, on, off, et les chaînes en forme de date. La conversion émet true, false, null, les nombres sans guillemets et les chaînes entourées de guillemets doubles. Le JSON résultant a les mêmes types que YAML, ce qui est la définition d’une conversion sans perte sur ce point.

La difficulté est le cas « 1.0 » : YAML le lit comme une chaîne, parce qu’un point seul ne suffit pas à faire un float, et JSON le transporte comme une chaîne. Un consommateur qui s’attendait à un nombre recevra une chaîne, ce qui est une surprise positive ici et qui justifie d’être vérifié au cas par cas sur les champs de version et les identifiants numériques avec zéros initiaux.

La conversion 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 YAML ni JSON 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 YAML, 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.

YAML 1.1 transformait 2024-01-01 en horodatage, ce que YAML 1.2 a corrigé. La conversion émet la valeur comme une chaîne JSON, avec des guillemets, ce qui est ce que la grande majorité des consommateurs attend. Si un client en aval a été écrit pour un parseur 1.1, il va interpréter la date comme un horodatage et la lire comme le 1er janvier 2024 à minuit UTC, ce qui peut être ou ne pas être ce que vous voulez.

La correction locale est de mettre la date entre guillemets dans YAML avant la conversion, ce qui force l’auteur YAML à la traiter comme une chaîne. C’est l’édition qui règle la question une fois pour toutes, et c’est aussi ce que la convention commune finit par adopter, parce que la date comme chaîne est plus prévisible que la date comme horodatage dans la grande majorité des usages.

La sortie est indentée de deux espaces, ce qui la rend directement collable dans un fichier de test ou dans un client comme curl. Pour un manifeste à soumettre à un cluster, c’est la bonne forme : lisible en revue, committable telle quelle, et analysable par n’importe quel client JSON sans configuration supplémentaire.

La forme compacte — sur une seule ligne, sans indentation — est utile pour envoyer dans une requête HTTP où chaque octet compte, mais c’est un autre outil. Cette conversion produit la forme lisible par défaut, parce que le but d’une conversion est presque toujours qu’une personne regarde le résultat avant de l’utiliser.

Les clés complexes — des mappings comme clés d’un autre mapping — sont légales en YAML et illégales en JSON, parce que JSON n’a que des chaînes comme clés. La conversion aplatit la clé en sa représentation sous forme de chaîne si possible, et refuse le document en avertissant si la clé ne peut pas être représentée. C’est rare et c’est volontaire : la conversion refuse d’inventer une forme de clé que JSON n’a pas.

Les ancres circulaires — un bloc qui se référence lui-même, directement ou par une chaîne d’alias — sont légales en YAML par construction paresseuse, et la conversion les développe jusqu’à une profondeur donnée ou refuse au-delà. Le JSON ne représente pas la circularité, et tenter de la sérialiser produit un fichier qui ne termine pas. Pour les fichiers de configuration, cela n’arrive jamais ; pour des données, cela arrive, et la conversion est prudente.

C’est du JavaScript dans votre onglet. Le YAML est analysé par un parseur chargé à la demande, JSON est écrit par la même logique de sérialisation, et aucune requête ne porte le document. Il n’y a pas d’inscription, pas de file d’attente, 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.