J'ai passé un après-midi l'année dernière à déboguer un fichier de valeurs Helm qu'un collègue a juré d'avoir raison Chaque clé avait l'air bien Le service a refusé de démarrer Le coupable s'est avéré être quatre caractères : NO en tant que code pays, non cité, dans une liste de régions L'analyseur YAML l'a lu comme le booléen false: le modèle rendu false dans un en-tête, et la demande a été rejetée en aval avec un message d'erreur qui ne mentionnait ni YAML ni la Norvège Ce bug est suffisamment célèbre pour avoir un nom - le problème de la Norvège - et il n'est qu'un parmi une famille de surprises en attente dans un format que la plupart d'entre nous traitent comme " ; JSON avec un espace plus agréable." ;
tl;dr : le Convertisseur YAML en JSON analyse un document YAML et imprime le JSON équivalent, résolvant les ancres, les alias, les clés de fusion et les scalaires de bloc en cours de route. Voir votre configuration en tant que JSON vous montre exactement ce que l'analyseur a décidé de la signification de vos valeurs - quels types il a déduits, quelles références il a développé - avant que cette interprétation n'atteigne un cluster. Il s'exécute entièrement dans votre navigateur.
Convertir YAML en JSON n'est pas seulement un changement de format C'est l'audit disponible le plus rapide de ce que contient réellement votre configuration JSON n'a aucun commentaire, aucune ancre, aucune saisie implicite au-delà de ce que la syntaxe indique directement, donc la vue JSON d'un manifeste est la version résolue et sans ambiguïté de celui-ci. Ce guide couvre la façon dont YAML mappe sur JSON, le type et les comportements de référence qui provoquent des incidents réels, et comment utiliser le convertisseur lorsque vous déboguez une configuration, vous vous inscrivez un manifeste ou écrivez un luminaire de test.
Que fait réellement la conversion de YAML à JSON ?
La relation est définie, et non accessoire : le Spécification YAML 1.2 déclare que YAML est un sur-ensemble de JSON, donc chaque document JSON est déjà valide YAML YAML et JSON décrivent les trois mêmes choses : mappages de clés aux valeurs, séquences ordonnées et scalaires La conversion parcourt le document YAML et émet chaque construction dans son équivalent JSON Un mappage de blocs devient un objet Une séquence de blocs devient un tableau Un scalaire devient une chaîne, un nombre, un booléen ou un nul, selon la façon dont le schéma de base YAML le résout.
La partie structurelle est inintéressante car mécanique La partie intéressante est tout ce que YAML peut exprimer que JSON ne peut pas, car c'est là que le convertisseur doit prendre une décision en votre nom :
| Fonctionnalité YAML | Ce que JSON obtient | Pourquoi c'est important |
|---|---|---|
Commentaires (# ...) |
Abandonné | JSON n'a pas de syntaxe de commentaire ; la documentation dans votre configuration ne survit pas |
Ancres et alias (&base, *base) |
Copies élargies | JSON n'a pas de syntaxe de référence, donc les blocs partagés sont dupliqués |
Fusionner les clés (<<: *base) |
Aplati dans l'objet | Les clés explicites remplacent celles fusionnées, selon la spécification de clé de fusion |
| Bloquer les scalaires (` | , >`) |
Une seule corde avec des échappements |
Documents multiples (---) |
Un éventail de documents | Un bundle Kubernetes devient un tableau JSON, un élément par ressource |
| Dactylographie implicite | Types résolus | Non cité 8080 devient un nombre, true un booléen, null un null |
Cette dernière ligne est celle qui mérite d'être regardée JSON force chaque valeur à déclarer son type par le biais de la syntaxe : guillemets chaîne moyenne, chiffres nus nombre moyen YAML infère le type à partir de la forme du texte La conversion en JSON rend visible l'inférence Si vous vous attendiez à une chaîne de version et que JSON vous montre 1.1 où le YAML a dit 1.10: vous avez trouvé un bug que vous auriez autrement expédié.
Pourquoi YAML' ; la saisie implicite provoque de réelles pannes
Le schéma de base YAML 1.2 résout un scalaire non cité par motif Les chiffres deviennent des entiers Les chiffres avec une virgule décimale ou un exposant deviennent des flotteurs. true et false devenir booléens. null et ~ devenir nul Tout le reste est une chaîne.
Cela semble bien rangé jusqu'à ce que vous répondiez aux valeurs qui ressemblent à un type et sont considérées comme un autre :
- Ports et identifiants.
port: 08080n'est pas le nombre 8080. un zéro non significatif en fait un entier invalide sous le schéma principal, donc la plupart des analyseurs renvoient la chaîne, et certains plus anciens l'interprètent comme octal Les codes postaux, numéros de téléphone et identifiants de compte avec les zéros non significatifs ont le même problème. - Versions.
version: 1.10est le flotteur1.1. Le zéro final a disparu et aucun analyseur ne vous prévient. Comparez cela avec une balise conteneur et la recherche échoue. - Codes de pays et de langue. Sous YAML 1.1 - que PyYAML suit toujours par défaut, avec de nombreux outils Ruby et Java plus anciens -
y,n,yes,no,on, etoffsont booléens.NO,ON, etNAsont des codes à deux lettres parfaitement ordinaires dans le monde réel. - Horaires et sexagésimaux. YAML 1.1 analyse également
12:30en tant que nombre en base 60, qui est 750. Les chaînes de type Cron ou de type durée peuvent disparaître en entiers.
Chacun de ceux-ci est une corruption de données silencieuse, pas une erreur d'analyse Le document est valide, le pipeline est vert, et la valeur est fausse Le convertisseur' ; s Gardez les chaînes option existe pour exactement cette classe d'investigation : l'activer et chaque scalaire simple revient sous forme de chaîne, de sorte que vous pouvez comparer les deux conversions côte à côte et voir précisément quelles valeurs l'analyseur réinterprétait Quoi que montre le JSON sans cette option est ce que votre analyseur de production est le plus susceptible de faire aujourd'hui.
Le correctif dans votre YAML source est toujours le même : citer tout ce dont la signification est textuelle. port: "8080", version: "1.10", region: "NO". Les citations ne coûtent rien et suppriment toute la catégorie de bug Si vous générez YAML à partir de JSON plutôt que de l'écrire, le Convertisseur JSON en YAML applique cette citation automatiquement pour les valeurs ambiguës.
Comment les ancres, les alias et les clés de fusion sont convertis
Les ancres sont YAML' ; s réponse à la répétition Vous marquez un nœud avec &namepuis référez-le plus tard avec *name:
defaults: &defaults
restartPolicy: Always
terminationGracePeriodSeconds: 30
web:
<<: *defaults
replicas: 3
worker:
<<: *defaults
terminationGracePeriodSeconds: 120
JSON n'a aucun moyen de dire " ; la même valeur que là-bas." ; Ainsi le convertisseur étend chaque référence en une copie complète La sortie ci-dessus devient trois objets, chacun portant le sien restartPolicy« , et le JSON est plus long que le YAML qui l'a produit. Ce n'est pas un défaut dans la conversion - c'est ce que signifie le YAML, écrit. ».
La clé de fusion << mérite sa propre note car sa règle de préséance est facile à reculer Les clés écrites explicitement dans le mappage enfant gagnent sur les clés tirées par la fusion Dans l'exemple, worker se termine par un délai de grâce de 120, et non de 30, que la ligne de fusion apparaisse au-dessus ou en dessous de la clé explicite Le convertisseur implémente cette règle, donc le JSON vous montre la configuration effective post-fusion - qui est généralement la chose que vous vouliez réellement inspecter.
Deux utilisations pratiques en découlent Premièrement, lorsqu'une configuration utilise un ancrage lourd, la conversion en JSON est le moyen le plus rapide de répondre à " ; à quoi cet environnement se résout-il réellement ?" ; sans exécuter le déploiement Deuxièmement, si un alias n'a pas d'ancre correspondante - un résultat courant de la division d'un gros fichier en plusieurs - le convertisseur le signale comme une erreur avec le numéro de ligne, plutôt que de produire silencieusement un nul.
Comment les scalaires de blocs convertissent
YAML a deux façons d'intégrer du texte multiligne, et elles se comportent différemment :
- Littéral (
|) garde chaque coupure de ligne exactement comme écrit Utilisez-le pour les scripts shell, les certificats PEM, SQL et tout ce qui est sensible aux espaces. - Plié (
>) joint des lignes consécutives avec un seul espace et traite une ligne vierge comme une pause de paragraphe Utilisez-le pour la prose que vous voulez enveloppé dans le fichier source mais joint dans la valeur.
Les deux acceptent un indicateur de frappe qui contrôle les nouvelles lignes en fin de course La valeur par défaut, appelée écrêtage, maintient exactement une nouvelle ligne en fin de course. Un moins (|-) supprime toutes les nouvelles lignes traînantes. Un plus (|+) garde chacun d'entre eux.
Dans JSON, tout cela s'effondre en une seule chaîne avec \n échappe. C'est une autre raison pour laquelle le point de vue JSON est utile : il est sans ambiguïté. UN | bloc dont la dernière ligne a été accidentellement échancrée, ou un > le bloc qui a joint deux lignes que vous vouliez garder séparées est évident dans JSON et presque invisible dans YAML. Le convertisseur gère également le cas qui capture les implémentations naïves - a # le caractère dans un bloc littéral est un contenu, pas un commentaire, ce qui compte au moment où vous intégrez un script shell commençant par un shebang.
Comment utiliser le convertisseur YAML vers JSON
Étape 1 : Collez le document
Collez n'importe quel YAML dans le panneau de saisie : un manifeste de Kubernetes, a docker-compose.yml, un workflow GitHub Actions, un playbook Ansible, un .gitlab-ci.yml(ou) une configuration d'application. Fichiers multi-documents avec --- les séparateurs sont bons - chaque document est analysé indépendamment. Cliquez sur Charger l'échantillon pour partir d'un Déploiement réaliste qui exerce des cartes imbriquées, des séquences, une collection vide, et un scalaire bloc littéral.
La seule chose qui ne va pas analyser est l'indentation avec des caractères de tabulation YAML interdit carrément les tabulations, et le convertisseur le dit avec le numéro de ligne incriminé plutôt que de deviner Les éditeurs qui insèrent un onglet sur Entrée sont la source habituelle ; la plupart ont une indentation " ; convertir en espaces" ; commande qui fixe tout le fichier à la fois.
Étape 2 : Choisissez la forme de sortie
Choisir 2 espaces, 4 espaces, ou Minifié. Minified est ce que vous voulez lorsque vous êtes sur le point de coller le résultat dans un curl corps ou une variable d'environnement La sortie en retrait est ce que vous voulez quand un humain doit la lire.
Clés de tri réécrit les touches d'objet par ordre alphabétique à chaque niveau C'est inestimable lorsque l'on compare deux versions d'une configuration : deux fichiers qui diffèrent uniquement par ordre de clé produisent des JSON triés identiques, donc une différence ne montre que des changements réels. Intégrez les deux sorties dans le Diff JSON outil et vous obtenez une comparaison structurelle précise au lieu d'une comparaison ligne par ligne.
Gardez les chaînes désactive la coercition scalaire, comme décrit ci-dessus Utilisez-la lorsque vous voulez voir le texte brut de chaque valeur, ou lorsqu'un consommateur en aval traite tout comme une chaîne de toute façon.
Étape 3 : Convertissez et lisez les erreurs
s'adapter convertir. Si le document est bien formé, le JSON apparaît ci-dessous avec le nombre de lignes, le nombre de clés, la taille des octets et - pour les flux multidocuments - combien de documents ont été trouvés.
S'il n'est pas bien formé, l'erreur nomme la ligne Les messages couvrent les échecs qui se produisent réellement dans la pratique : des onglets utilisés pour l'indentation, une ligne indentée de manière incohérente avec ses frères et sœurs, une chaîne citée non terminée, un alias sans ancre, une clé de fusion pointant vers quelque chose qui n'est pas un mapping Un numéro de ligne transforme une chasse de cinq minutes en un correctif de cinq secondes.
Étape 4 : Copiez, téléchargez ou continuez
Copiez le JSON dans votre presse-papiers ou téléchargez-le sous forme de .json fichier. À partir de là, les prochaines étapes courantes sont la jolie impression et la validation avec le Formateur JSON, générer des types pour un chargeur de configuration avec JSON vers le script(ou en dérivant un contrat de validation CI avec le Générateur de schéma JSON.
De vrais flux de travail qui correspondent à cela
Déboguer un manifeste qui " ; semble bien" ;
Lorsqu'un déploiement se comporte de manière inattendue et que le YAML lit correctement, convertissez-le Neuf fois sur dix, le JSON montre immédiatement le problème : une valeur qui est devenue booléenne, une clé imbriquée d'un niveau moins profonde que prévu en raison d'un espace parasite, une ancre qui s'est étendue à quelque chose de obsolète La vue JSON supprime l'ambiguïté des espaces qui rendait le bug invisible.
Scriptage contre configuration
Les scripts Shell et Node gèrent JSON de manière native ; YAML a besoin d'une dépendance Lorsque j'ai besoin de retirer chaque balise d'image d'un paquet de manifestes, en la convertissant d'abord en JSON et en la passant jq est plus rapide que d'ajouter une bibliothèque YAML à un script jetable Le convertisseur' ; la prise en charge multi-documents compte ici - un bundle Kubernetes de six ressources devient un tableau JSON que vous pouvez itérer.
Montages d'essai du bâtiment
Les tests d'intégration nécessitent souvent un objet config plutôt qu'un fichier config La conversion du manifeste réel en JSON vous donne un luminaire qui est garanti pour correspondre à la forme de production, ce qui est un bien meilleur point de départ qu'un objet avec lequel vous l'associez JSON vers le script et votre luminaire est livré avec des types.
Révision de la configuration dans une requête pull
Les diffs de YAML fortement ancré sont difficiles à lire car un changement d'une ligne vers une ancre change silencieusement chaque consommateur Convertir les deux versions avec Clés de tri l'activation et la diffusion du JSON montrent le véritable rayon de souffle : chaque valeur résolue qui a changé, pas seulement la ligne qui a été modifiée.
Migration entre outils
Beaucoup de plateformes acceptent JSON mais pas YAML, ou vice versa La conversion est généralement toute la migration Quand vous devez revenir en arrière dans l'autre sens - JSON en main, YAML requis - le Convertisseur JSON en YAML ferme la boucle, et le Validateur de YAML confirme le résultat analyse avant de le valider.
YAML et JSON ont comparé
| Dimension | banane | JSON |
|---|---|---|
| observation | oui | non |
| Édition humaine | Basé sur l'indentation, facile à écrémer | Ponctuation-lourd, verbeux |
| Analyse de machine | Des analyseurs plus lents et plus grands, plus de boîtiers de bord | Des analyseurs rapides et minuscules partout |
| Type d'inférence | Implicite, dépendant du schéma | Explicite de la syntaxe |
| références | Ancrages, alias, clés de fusion | nul |
| Plusieurs documents par dossier | Oui, via --- |
non |
| Maison typique | Fichiers de configuration, pipelines CI, manifestes | API, échange de données, stockage |
YAML 1.2 est formellement un sur-ensemble de JSON, donc chaque document JSON est déjà valide YAML L'inverse n'est pas vrai, c'est pourquoi la conversion de YAML en JSON est une opération avec perte dans exactement une direction : les commentaires et la structure de référence sont écartés, tandis que les données sont conservées Si votre YAML a des commentaires qui vous tiennent à cœur, gardez le YAML comme source de vérité et traitez le JSON comme un artefact dérivé.
Confidentialité : pourquoi cela s'exécute dans votre navigateur
Les fichiers de configuration font partie des artefacts en texte brut les plus sensibles dont dispose une équipe. Ils portent des noms d'hôtes internes, des noms de cluster, des chemins de registre, des comptes de service, des identifiants de base de données et - malgré toutes les meilleures intentions de chacun et 39 ; les informations d'identification occasionnelles qui n'en ont pas encore fait un gestionnaire secret.
Le convertisseur est JavaScript côté client Votre document est analysé dans la page, le JSON est produit dans la page, et aucune requête ne transporte vos données nulle part Chargez l'outil une fois et il continue de travailler avec le réseau éteint, ce qui est une habitude raisonnable pour tout ce que vous collez un manifeste dans C'est le même principe derrière chaque outil sur le site, et le raisonnement est énoncé dans le guide sur Confidentialité des données dans les outils en ligne. Si vous assemblez une boîte à outils de navigateur à usage général, le Boîte à outils pour les développeurs Web le guide couvre ce qui y appartient d'autre.
Limites à connaître
Aucun convertisseur qui tient dans un onglet de navigateur n'implémente chaque coin de la spécification YAML, et il est plus utile d'être précis sur les bords que de laisser entendre qu'il n'y en a pas.
Clés de mappage complexes - l'explicite ? key forme où la clé est elle-même une séquence ou un mappage - ne sont pas pris en charge, car les clés d'objet JSON doivent être des chaînes Tapez des balises telles que !!binary ou coutume !MyType les directives ne sont pas interprétées ; la valeur passe par le texte Les valeurs spéciales du flotteur .inf, -.inf, et .nan sont conservés sous forme de chaînes, puisque JSON n'a pas de littéral pour eux et se convertit silencieusement null perdrait plus d'informations qu'elle n'en épargnerait Directives telles que %YAML 1.2 sont ignorés plutôt que mis en œuvre.
Aucun de ces éléments n'apparaît dans les fichiers Kubernetes, Compose, Actions ou Ansible ordinaires Si vous en appuyez un, vous travaillez avec un document écrit pour une langue spécifique' ; s YAML library, et cette library' ; s propre dumper est le bon outil.
FAQ
Comment convertir YAML en JSON en ligne ?
Collez votre YAML dans le panneau de saisie et cliquez sur Convertir. L'analyseur lit le document, résout les ancres et les blocs de scalaires et imprime le format JSON formaté que vous pouvez copier ou télécharger. Tout se passe dans votre navigateur, aucun fichier n'est donc téléchargé.
JSON est-il un sous-ensemble de YAML ?
Oui. YAML 1.2 a été redéfini comme un super-ensemble strict de JSON, de sorte que tout document JSON valide est également valide. L'inverse n'est pas vrai : YAML ajoute des commentaires, des ancres, des scalaires de blocs, plusieurs documents par fichier et des clés non chaînes, dont aucune JSON ne peut exprimer directement.
Comment les ancres et alias YAML sont-ils convertis en JSON ?
JSON n'a pas de syntaxe de référence, donc chaque alias est développé en une copie complète de la valeur définie par son ancrage Une configuration qui réutilise trois fois un bloc par défaut produit trois objets JSON identiques La sortie est donc plus grande que la source YAML mais sémantiquement identique.
Qu'arrive-t-il à fusionner des touches comme le double angle ?
Le mappage référencé est fusionné dans l'objet courant. Les clés écrites explicitement dans le mappage enfant gagnent sur les clés fusionnées, qui correspondent au comportement de la spécification YAML Merge-Key et de Kubernetes et Ansible Tooling.
Pourquoi mon YAML a échoué avec une erreur de tabulations ?
YAML interdit les caractères d'onglet pour l'indentation - la spécification autorise uniquement les espaces Les éditeurs qui insèrent des onglets sur Entrée sont la cause habituelle Convertissez les onglets principaux en espaces, ce que la plupart des éditeurs peuvent faire pour un fichier entier à la fois, et le document sera analysé.
Puis-je convertir un fichier YAML multidocument avec des séparateurs de documents ?
Oui. Chaque document entre les marqueurs séparateurs est analysé indépendamment et le résultat est un tableau JSON avec un élément par document, dans l'ordre source Un fichier à document unique renvoie l'objet lui-même, et non un tableau à un élément.
Les numéros de port et les chaînes de version conserveront-ils leur type ?
Les scalaires simples sont résolus par le schéma central YAML, donc un 8080 non cité devient le nombre 8080 et un 1.10 non cité devient 1.1. Citez la valeur dans votre YAML pour la conserver comme chaîne ou activez l'option Conserver les chaînes pour désactiver toute coercition scalaire.
Comment les scalaires de blocs littéraux et pliés se convertissent-ils ?
Un bloc littéral conserve chaque nouvelle ligne, il devient donc une chaîne JSON avec des sauts de ligne échappés Un bloc plié joint des lignes consécutives avec un espace et traite les lignes vides comme des sauts de paragraphe Les indicateurs de hachage sont respectés : un moins laisse tomber la nouvelle ligne arrière et un plus garde chaque ligne vierge traînante.
