Erreurs courantes de conversion JSON en YAML et comment les corriger

Erreurs d'indentation

La structure YAML est définie par des espaces, pas par des accolades. JSON vous indique exactement où un objet se termine par}; YAML s'attend à ce que chaque clé imbriquée soit indentée d'une étape cohérente (presque toujours deux espaces dans les écosystèmes d'outils) sous son parent. Lorsque vous convertissez JSON en YAML, un formateur bâclé (ou des modifications manuelles) peut décaler un enfant d'une colonne vers la gauche afin qu'il devienne un frère de ce que vous vouliez dire en tant que parent.

Imaginez transformer ce JSON en YAML:

Siports'aligne avecserverau lieu de s'imbriquer en dessous, les analyseurs traitentportcomme une clé de niveau supérieur, et nonserver.port. Certains chargeurs fusionnent alors de manière inattendue ou échouent avec « les valeurs de mappage ne sont pas autorisées ici ». La catégorie erreurs JSON vers yaml qui fait perdre le plus de temps à l'ingénierie est exactement celle-ci: un texte d'apparence valide qui est analysé dans le mauvais arbre.

Correction: choisissez une largeur de retrait (2 espaces), interdisez les tabulations dans YAML validé et la sortie du convertisseur de différence par rapport à un émetteur connu (yq, votre IDE ou YAML Validator). Si vous avez besoin d'un flux de travail reproductible à partir de zéro, consultez how to convert JSON to YAML avant d'automatiser les pipelines.

Les fonctionnalités de l'éditeur aggravent la situation: des « extraits » qui insèrent des onglets, de jolies imprimantes qui ne redistribuent que la moitié du fichier ou des tampons de collage qui normalisent le CRLF tout en décalant les espaces. Lors du débogage des erreurs JSON vers yaml, réduisez visiblement les espaces (cat -Aou IDE « render whitespace ») avant de blâmer le convertisseur.

Problèmes de type de données

Les littéraux JSON sont explicites:true,false,null, nombres, chaînes. YAML 1.1 (encore courant dans la nature) traite yes/no/on/off comme des booléens lorsqu'ils ne sont pas cités. JSON n'émet jamais ces jetons, mais les humains qui modifient YAML après la conversion les introduisent parfois, ou un aller-retour via un autre outil échange les citations.

Pire: un null non cité dans YAML est très bien, mais un Null ou un NULL parasite peut se comporter différemment selon le mode de l'analyseur. Idem pour les horodatages: une chaîne comme 2024-01-15 peut devenir un type de date si le chargeur est permissif.

En fonction de l'analyseur,yesdevient un booléentrue,nullreste nul etcutoffpeut devenir une date analysée, et non une chaîne de six caractères, ce qui brise les API qui attendent"2024-01-15"textuellement.

Correction: citez tout ce qui doit rester une chaîne:enabled: "yes"lorsque le contrat veut le mot « oui »,cutoff: "2024-01-15"lorsque les consommateurs comparent des chaînes. Après la conversion, affirmez les types dans les tests ou la validation du schéma (schéma JSON, OpenAPI ou chargeurs YAML stricts dans CI).

Les surprises numériques comptent également: JSON001n'est pas valide; YAML pourrait volontiers analyser les jetons d'apparence zéro différemment selon la version. Tenez-vous-en aux formulaires JSON normaux avant la conversion, puis citez les identifiants qui doivent conserver les zéros non significatifs (codes postaux, segments de version traités comme des chaînes).

Problèmes de formatage de tableau

Les tableaux JSON sont délimités par[… ​​]; les éléments de séquence ne peuvent pas « dériver ». Les listes YAML utilisent des marqueurs-dont le niveau d'indentation décide quel objet possède les éléments. Un échec classique après l'automatisation de JSON vers yaml est un tableau à un seul élément qui devient un scalaire en ligne ou une liste d'éléments qui se collent à la mauvaise clé parent.

JSON comme{"items": [{"id": 1}, {"id": 2}]}doit devenir une liste-en retrait sousitems:. Si un-est en retrait, vous avez soudainement plusieurs documents ou une erreur d'analyse. Les chaînes multilignes et les listes imbriquées amplifient le problème: les manifestes Kubernetes et les configurations CI regorgent des deux.

Les tableaux vides sont importants:[]dans JSON devrait devenir une syntaxe de liste YAML explicite (modèlesitems: []ouitems:\n []selon le style) — évitez les scalaires ambigus commeitems:sans rien suivre à moins que votre linter ne l'interdise. Les tableaux mixtes (objets et chaînes dans une seule liste) sont des JSON valides mais faciles à mettre en retrait une fois aplatis.

Correction: ne fusionnez jamais manuellement les marqueurs de liste après la conversion; régénérer à partir de JSON lorsque les listes semblent suspectes. Vérifiez visuellement que chaque-partage la même colonne que ses frères et sœurs et se trouve plus profondément que la clé à laquelle il appartient.

Exemple: listes qui ont survécu intactes à la conversion

À partir de JSON{"routes": [{"path": "/api", "upstream": "svc"}, {"path": "/health", "upstream": "direct"}]}, YAML stable maintient les blocs frères-alignés:

Siupstream: directs'aligne sousroutes:au lieu de sous le deuxième- path, vous venez d'inventer une table de routage différente — une classe subtile d'erreurs JSON vers yaml qui transmet les peluches mais interrompt le routage.

Caractères spéciaux

Les chaînes contenant:,#,{,},[,]ou-de début doivent être citées dans YAML ou le scanner attache une signification à la ponctuation (#démarre un commentaire;:démarre un mappage valeur). Les URL et les valeursconnection_stringsont des victimes fréquentes.

Tout ce qui suit#peut être traité comme un commentaire sauf si vous citez:

`yaml
message: "Error: disk full (see log #42)"
`

Correction: adoptez une règle simple: si la valeur ressemble à du code, à une URL ou contient#ou: , placez-la entre guillemets doubles et échappez à"interne en tant que\"si nécessaire.

Les chaînes multilignes de JSON (\\n) explosent parfois en blocs littéraux YAML (|) ou pliés (>) pendant les sauts d'outillage - très bien si chaque chargeur en aval est d'accord. Sinon, conservez les échappements sur une seule ligne jusqu'à ce que vous normalisiez.

Comment éviter les erreurs

Traitez JSON → YAML comme une étape de compilation, et non comme un collage ponctuel:

Lorsque des erreurs persistent, JSON Validator sur le JSON source élimine la moitié des cas de « déchets dans » avant qu'ils ne deviennent des arborescences YAML déroutantes.

Si vous envoyez des configurations à Kubernetes après la conversion, combinez cette liste de contrôle avec la procédure pas à pas du manifeste travaillé dans Convert JSON to YAML for Kubernetes (With Examples).

La plupart des erreurs JSON vers yaml ne sont pas mystérieuses: il s'agit d'indentation, de saisie implicite, de propriété de liste ou de citation. Rendez ces quatre dimensions ennuyeux et explicites et vos configurations cesseront d'échouer à 23 heures. la nuit du déploiement.