La première fois que Yaml m'a bien brûlé, c'était un code de pays. Je déplaçais une configuration locale des fichiers JSON d'un projet Laravel dans un format YAML favorable au déploiement, convertissant à la main au fur et à mesure de la « modification des accolades » en indentation. "country": "NO". Dans YAML, non cité, that' ; n'est pas une chaîne - selon les règles YAML 1.1 que PyYAML et de nombreux autres analyseurs appliquent toujours, NO est le booléen false. Le script de déploiement, écrit en Python, a joyeusement évalué les utilisateurs norvégiens en tant que country: false et je les ai acheminés vers le lieu de secours Ce bug a un nom - la communauté l'appelle le problème de la Norvège - et j'ai pu le découvrir de manière artisanale, un ticket de support confus à la fois.
La conversion manuelle de JSON en YAML semble triviale et est en fait un champ de mines, car les deux formats ont des idées extrêmement différentes sur ce que signifie un mot nu. En JSON, tout est explicite : les chaînes ont des guillemets, les chiffres ne sont pas, true/false/null sont des mots-clés, fin de l'histoire. Dans YAML, un scalaire non coté interprété: no devient faux, 3000 devient un entier, 1.10 devient le flotteur 1.1 (Au revoir, chaîne de version), 08 étouffe certains analyseurs comme une octale invalide, et une valeur avec un espace de deux-points parasite devient une carte imbriquée au moment où vous vous y attendez le moins. Chacun d'entre eux est une corruption de données silencieuse - le fichier analyse bien, les types sont tout simplement faux.
un Convertisseur JSON en YAML cela comprend ces règles vous donne la lisibilité pour laquelle YAML a été inventé sans la roulette de type. Celui que j'ai construit pour Toolz.dev détecte tous les scalaires ambigus - sosies booléens, sosies numériques, valeurs héritées de YAML 1.1, chaînes avec des caractères spéciaux - et cite exactement ceux-là, donc ce qui était une chaîne dans votre JSON est toujours une chaîne après que l'outil suivant analyse le YAML. Ce & devis ; exactement ceux-là & devis ; importe : citer tout Ce serait également sûr, mais la sortie s'arrête de ressembler à un YAML idiomatique, et idiomatique est tout.
Ce guide explique comment la conversion gère les arêtes vives de YAML, pourquoi JSON est techniquement déjà YAML (et pourquoi ce fait ne vous aide pas), et les flux de travail Kubernetes, CI et Docker composent chaque semaine.
tl;dr : Collez JSON dans le Toolz.dev JSON en YAML Convertisseur(en), choisissez l'indentation à 2 ou 4 espaces, et obtenez un YAML de type bloc propre avec un devis de type sécurisé -
"3000"reste une chaîne,"no"reste une chaîne,"1.10"Reste une version. L'ordre des clés est conservé, les collections vides sortent comme[]et{}, et tout s'exécute côté client, donc les configurations avec des secrets ne quittent jamais votre navigateur. Retour aller-retour avec le Validateur de YAML, et formatez la source en premier avec le Formateur JSON.
n'est-il pas déjà valide YAML ?
Oui - et c'est & #39 ; c'est le " ; oui" ; le plus inutile dans la gestion de la configuration YAML 1.2 a été explicitement conçu comme un sur-ensemble de JSON : chaque document JSON valide analyse comme YAML valide Vous pourriez coller JSON brut dans un manifeste de Kubernetes et kubectl l'accepterait.
Personne ne le fait, car la raison pour laquelle YAML existe est Ergonomie humaine. Les manifestes Kubernetes, les flux de travail GitHub Actions, les fichiers Docker Compose, les livres de lecture Ansible, les configurations Home Assistant - ce sont des YAML car les gens les lisent et les modifient manuellement en permanence, et replicas: 3 sous un bloc en retrait, les analyses en bloc sont mieux que {"replicas":3} niché dans des accolades. Quand quelqu'un dit "convertir JSON en YAML", il veut dire de style bloc Yaml : indentation au lieu de bretelles, - Des tirets au lieu de tableaux entre crochets, aucun guillemet n'est nécessaire.
Cette dernière clause est celle où vit la difficulté. Passer de la syntaxe tout explicite de JSON à la syntaxe minimale de YAML Décider, pour chaque chaîne, s'il peut perdre ses devis en toute sécurité- et cette décision nécessite de connaître les règles de résolution scalaire de YAML' ; mieux que la plupart des humains ne le font de manière fiable à 17 heures un vendredi. C'est le travail réel d'un convertisseur ; la partie accolades-indentation est triviale.
Qu'est-ce qui se casse silencieusement lorsque vous convertissez à la main ?
Les cas d'échec se répartissent en quatre familles, et j'ai frappé chacune d'entre elles dans des configurations réelles :
Les sosies booléens. YAML 1.1 se résout yes, no, on, off, y, n (dans divers boîtiers) comme booléens, et Yaml 1.2 garde true/false. PyYAML - toujours la bibliothèque YAML par défaut dans la plupart des bases de code Python - implémente 1.1. Donc "debug": "no" converti à la main en debug: no se transforme debug: false Dans votre outil Python, déployez des outils. Le problème de la Norvège (NO → false) et son cousin le problème de l'Ontario (ON → true) sont les plus grands succès de cette famille.
Nombres de sosies. "port": "3000" converti en port: 3000 est maintenant un entier. Kubernetes fait & #39 ; il s'en soucie dans certains domaines et échoue dans d'autres - les valeurs env var, par exemple, doivent être des chaînes, et kubectl apply y rejettera un entier avec une erreur qui nomme le champ mais pas le pourquoi. Les chaînes de version sont pires car rien n'échoue : version: 1.10 Analyse comme le flotteur 1.1et votre script de déploiement signale volontiers la mauvaise version pour toujours. Zéros principaux - codes postaux, numéros de téléphone, identifiants d'apparence octale comme 0755- complétez la famille.
caractères spéciaux. Un deux-points suivi d'un espace à l'intérieur d'une valeur non cotée commence un mappage (message: error: not found est une erreur d'analyse ou une carte imbriquée, selon l'analyseur). un # Démarre un commentaire à mi-valeur. de premier plan *, &, ! entrer en collision avec l'ancre, l'alias et la syntaxe de tag. Les chaînes de nouvelles lignes doivent s'échapper ou bloquer les scalaires.
la chaîne vide. Le vide non coté dans YAML est null, pas "". Tout champ JSON contenant une chaîne vide doit sortir entre guillemets ou changer de type.
le convertisseur vérifie chaque chaîne par rapport aux quatre familles et cite celles qui en ont besoin - et seulement celles-là. production sort à nu parce que c'est sans ambiguïté ; "3000", "no", "1.10", et "" Sortez cité parce qu'ils ne le sont pas. Il y a aussi une "toute les chaînes" pour vous quand vous nourrissez un analyseur auquel vous ne faites pas confiance et que vous voulez que la résolution scalaire n'ait pas lieu.
Comment convertir JSON en YAML avec l'outil ?
Étape 1 : Collez votre JSON
Tout JSON valide fonctionne - objets, tableaux, emboîtement profond, unicode. Le bouton Charger l'échantillon vous donne une configuration de service réaliste qui exerce les cas intéressants : un port de chaîne numérique, un booléen, un tableau vide, des cartes imbriquées Si votre entrée a des problèmes de syntaxe, le convertisseur signale l'erreur exacte parser' ; s plutôt que de convertir un document tronqué ; pour la recherche alors que L'erreur est dans une grosse goutte, la Formateur JSON est le meilleur microscope.
Étape 2 : Choisissez l'indentation
Deux espaces ou quatre. Deux est la convention écrasante : les documents Kubernetes, les exemples d'actions GitHub, les références Docker Compose et le yamllint les valeurs par défaut l'utilisent toutes - mais certaines équipes standardisent sur quatre pour plus de lisibilité lors d'une imbrication profonde. Quel que soit le choix, le convertisseur est cohérent à ce sujet, y compris le cas subtil des éléments de liste sous une clé, où l'indentation manuelle incohérente est une source classique de " ; les valeurs de mappage ne sont pas autorisées ici et par quota ; erreurs.
Étape 3 : Convertir et réviser
La sortie apparaît avec les comptes de ligne et d'octets Écrétez-le une fois - non pas pour l'exactitude (cela' ; c'est le travail du convertisseur' ; s) mais pour vérifier la santé mentale des décisions de citation par rapport à vos attentes. Voir PORT: "3000" cité tandis que NODE_ENV: production N'est-ce pas l'outil qui vous indique quelles valeurs étaient dangereuses.
Étape 4 : Copiez ou téléchargez
Copier dans le presse-papiers pour le coller dans un manifeste existant ou télécharger en tant que .yaml fichier. La sortie utilise uniquement des espaces - YAML interdit les onglets pour l'indentation, ce qui vaut la peine d'être connu lorsque vous modifiez ultérieurement le fichier dans un éditeur configuré pour l'indentation des onglets.
JSON vs Yaml : Quand chaque format gagne-t-il ?
| JSON | banane | |
|---|---|---|
| Lire/édité par | Machines, API | Humains, équipes de l'OPS |
| observation | pas dans la spécification | # commentaires - la fonctionnalité qui tue pour les config |
| Type explicite | Total - les citations décident de tout | Résolution scalaire - le contexte décide |
| Chaînes multilignes | \n s'échappe uniquement |
Bloquer les scalaires (` |
| Vitesse d'analyse et ubiquité | Le plus rapide, partout | Analyseurs plus lents et plus lourds |
| canons à pied | Des virgules de fuite, c'est à peu près tout | Problème de Norvège, onglets, dérive d'indentation, troncature de version |
| Habitat naturel | Charges utiles API, package.json, échange de données |
Kubernetes, Pipelines CI, Composer, Ansible |
Le modèle derrière la table : JSON gagne partout où une machine écrit et une machine lit ; YAML gagne partout où une machine lit mais un humain écrit. La configuration se situe directement dans la deuxième catégorie, c'est pourquoi la direction JSON-YAML est la direction courante : les données commencent leur vie dans une API ou une exportation de base de données et doivent devenir quelque chose qu'une équipe d'opérations peut maintenir. Le voyage inverse, YAML retour à JSON lisible par machine, est ce que le Validateur de YAML poignées - collez YAML, obtenez une validation plus le JSON équivalent.
Quels sont les flux de travail quotidiens de cette conversion ?
Manifestes Kubernetes à partir de la sortie de l'API
kubectl get deployment my-app -o json vous donne JSON ; le manifeste que vous vérifiez dans Git est YAML. La conversion des réponses API en YAML propre est le moyen le plus rapide de démarrer un manifeste à partir d'une ressource en direct - convertir, supprimer le serveur rempli status et metadata.managedFields blocs, et vous avez un point de départ déclaratif. Le devis de type-safe gagne son obligation ici : valeurs env dans Kubernetes moût être des chaînes, et l'insistance du convertisseur sur le citation "3000" est la différence entre kubectl apply réussir et échouer.
Configuration du pipeline CI
Les actions GitHub et GitLab CI sont uniquement YAML. Lorsque I' ; m génère des étapes de flux de travail par programme - une matrice de versions PHP et Node pour tester WP Adminify contre, disons - le générateur produit naturellement JSON, et la dernière étape est la conversion Les chaînes de version dans les matrices de test sont exactement les valeurs qui sont mutilées par une conversion naïve : une matrice de ["1.9", "1.10", "1.11"] Convertis manuellement sans devis Tests contre PHP 1.1 deux fois. le Collection d'outils de codage Couvre davantage ce modèle de génération-puis-convertir.
Docker composer d'inspecter la sortie
docker inspect émet JSON ; docker-compose.yml veut YAML. Inverser l'ingénierie d'un fichier Compose à partir d'un conteneur en cours d'exécution - ports, volumes, env - est une tâche de conversion et de pruneau. Tableaux et objets vides convertis en [] et {} Flow Syntaxe, qui est accepté et qui permet de garder la scène de taille lisible.
Rendre la configuration révisable
Celui-ci est sous-estimé : les configurations JSON avec des dizaines de clés imbriquées sont misérables dans la révision du code, en partie parce qu'elles ne peuvent pas porter de commentaires. La conversion en YAML vous permet d'annoter pourquoi rateLimit est 250 juste à côté de la valeur. Pour l'examen lui-même, jumeler la conversion avec un Diff structural d'avant/après JSON garde la question "ce qui a réellement changé" alors que la version YAML gère la "pourquoi".
Documents OpenAPI et de schéma
Les spécifications OpenAPI sont généralement rédigées dans YAML mais générées et servies de JSON. La conversion d'une spécification générée en YAML pour l'édition humaine - puis la validation de l'aller-retour - est un flux de travail standard de l'équipe API, et les garanties de fidélité (ordre des clés préservé, types cités) signifient que la version YAML reste diffable par rapport à son ancêtre JSON.
Pourquoi la conservation des commandes de clés est-elle importante ?
Selon la spécification JSON, l'ordre des clés d'objet n'a aucune signification {"a":1,"b":2} et {"b":2,"a":1} sont le même objet. Ainsi, un convertisseur peut trier les clés alphabétiquement et être techniquement correct. Ce serait aussi pratiquement hostile, car les fichiers de configuration sont lire Dans l'ordre : un déploiement Kubernetes se lit naturellement comme apiVersion, kind, metadata, spec- trier ces éléments par ordre alphabétique produit un manifeste qui analyse de manière identique et se lit comme une demande de rançon.
Le convertisseur émet des clés dans l'ordre source. Votre modèle mental du document survit à la conversion, le YAML diffère proprement des conversions précédentes de la même source et des ordres conventionnels (nom avant la valeur, apiVersion Premièrement) Restez conventionnel. si vous avoir envie ordre canonique à des fins de comparaison, that' ; est une préoccupation diff-outil - le Vérificateur de différentiel JSON Compare par clé, quel que soit l'ordre, qui est le bon calque pour ce problème.
Est-il sécuritaire de convertir des configurations contenant des secrets ?
La configuration est le texte le plus secret-dense qu'un développeur gère - les URL de base de données avec des mots de passe intégrés, les jetons API dans les blocs env, les noms d'hôtes internes qui mappent votre infrastructure It' ; s aussi exactement ce que les gens collent dans les convertisseurs en ligne, généralement à mi-déploiement, généralement à la hâte.
le Convertisseur Toolz.dev fonctionne entièrement dans votre navigateur : analyse, analyse scalaire, sérialisation - tout cela est JavaScript côté client, aucune requête réseau ne transporte vos données et l'outil continue de fonctionner avec votre connexion coupée. Cela' ; est un fait d'architecture et non une promesse de politique de confidentialité. La philosophie de conception du navigateur derrière toute la boîte à outils est présentée dans le Guide d'outils pour les développeurs Web; cet outil est cette philosophie appliquée au type de document le plus sensible de votre flux de travail.
La mise en garde évidente est que la conversion côté client protège le transformation. Là où vous collez la sortie par la suite, c'est sa propre décision de sécurité.
FAQ
Comment convertir JSON en YAML en ligne ?
Collez votre JSON dans le Convertisseur JSON en YAML(en anglais), choisissez l'indentation à 2 ou 4 espaces, et cliquez sur Convertir Vous obtenez YAML de type bloc avec citation sans danger, prêt à copier ou à télécharger en tant que fichier.yaml La conversion s'exécute entièrement dans votre navigateur - rien n'est téléchargé.
JSON est-il déjà valide YAML ?
Techniquement oui - YAML 1.2 est un sur-ensemble de JSON, donc tout document JSON valide s'analyse comme YAML. Mais la syntaxe JSON bat YAML' ; s objectif de lisibilité La conversion produit YAML de type bloc avec indentation au lieu d'accolades, ce que Kubernetes manifeste, les flux de travail CI et les fichiers Compose s'attendent à ce que les humains lisent et modifient.
Quel est le problème de la Norvège dans YAML ?
Selon les règles scalaires YAML 1.1, que des analyseurs comme PyYAML appliquent toujours, les valeurs non citées non, oui, activé et désactivé s'analysent comme booléens - de sorte que le code pays NON devient silencieusement faux. Le convertisseur l'empêche en citant automatiquement toute chaîne qu'un analyseur YAML pourrait interpréter comme booléenne, numérique ou nulle.
Les chaînes numériques comme "3 000" restent-elles des chaînes après la conversion ?
Oui. Le convertisseur détecte les chaînes qui ressemblent à des nombres et les citent dans la sortie, donc "3 000" reste une chaîne au lieu de devenir l'entier 3 000. Cela compte pour les ports, les numéros de version tels que "1.10" (qui seraient autrement tronqués au float 1.1), les codes postaux et les identifiants avec des zéros en tête.
Le convertisseur conserve-t-il l'ordre de mes clés JSON ?
Oui. Les clés sont émises dans l'ordre dans lequel elles apparaissent dans le JSON source Les clés de tri seraient techniquement valides - l'ordre des objets JSON n'a aucune signification per RFC 8259- mais l'ordre source maintient les config lisibles dans leur structure conventionnelle et maintient le YAML diffable par rapport à sa source JSON.
Puis-je utiliser la sortie directement dans Kubernetes ou Docker Compose ?
Oui. La sortie est YAML standard de style bloc en retrait avec des espaces (jamais des onglets), que kubectl, Docker Compose, GitHub Actions et GitLab CI acceptent tous Les valeurs qui doivent être des chaînes - comme les valeurs Kubernetes env var - sortent cotées, évitant ainsi les erreurs de type que kubectl soulève sur les chiffres non cités.
Comment reconvertir YAML en JSON ?
Utilisez le Validateur de YAML sur Toolz.dev - il analyse votre YAML, signale les erreurs de syntaxe et génère le JSON équivalent. Avec le convertisseur JSON vers YAML, il vous offre un aller-retour complet entre les deux formats.
Est-il sécuritaire de convertir des fichiers de configuration contenant des secrets ?
Oui. La conversion s'exécute entièrement en JavaScript dans votre navigateur - aucune requête réseau ne transporte vos données, rien n'est stocké ou enregistré et l'outil fonctionne hors ligne. Les configurations avec les informations d'identification de la base de données, les jetons API ou les noms d'hôtes internes ne quittent jamais votre machine.
YAML' ; s la lisibilité est réelle, et ses arêtes vives aussi - le format résout les types à partir du contexte, et le contexte est exactement ce que la conversion manuelle se trompe Un convertisseur qui connaît les règles scalaires vous donne la configuration lisible sans la corruption de type silencieux : Convertissez votre JSON, survolez le devis qu'il a choisi et expédiez un manifeste où la Norvège est encore un pays.
