XML naar YAML omzetten

XML besteedt ruwweg de helft van zijn tekens aan zeggen waar een element eindigt. YAML zegt dat met inspringing, dus komt hetzelfde document er aanzienlijk korter uit en is elk nestniveau één visuele stap in plaats van een gekoppeld paar om te scannen. Op een Maven-pom of een web.config is dat het verschil tussen scrollen en lezen.

De structuur verandert niet. Elk element wordt een sleutel, zijn kinderen worden de mapping eronder, en tekst wordt de waarde. Er wordt niets herschikt en niets samengevat, dus wat je bekijkt is hetzelfde document met de leestekens verwijderd — precies wat je wilt als het doel is te begrijpen wat het bestand zegt.

Attributen komen over als sleutels met een @-prefix, en een element dat zowel attributen als tekst draagt, bewaart die tekst onder de sleutel #text. Beide worden met aanhalingstekens geschreven, want YAML behandelt @ als een gereserveerd teken aan het begin van een kale scalar en # als het begin van een opmerking.

Het oogt als ruis en het is correctheid. Bewerk je het bestand met de hand, houd die aanhalingstekens dan aan: ze verwijderen levert YAML op die ofwel niet parseert, ofwel — bij #text — de rest van de regel stilzwijgend in een opmerking verandert en de waarde kwijtraakt. Hetzelfde geldt als je een sleutel hertypt terwijl je de uitvoer omvormt tot een values-bestand.

Dit is de sterkste reden om de omzetting te doen. XML diffen is ellendig omdat een wijziging één niveau diep zich toont als meerdere regels tags, en herformatteren door een tool het hele bestand herschrijft. Beide versies omzetten en de YAML diffen toont de gewijzigde waarden op hun eigen regels met hun sleutelpad erboven zichtbaar.

Eén voorbehoud maakt of breekt het. Omdat één herhaald element een mapping wordt en twee een lijst, verandert een versie die een tweede dependency toevoegde de vorm van die tak en niet alleen zijn inhoud, dus toont de diff het hele blok als herschreven. Dat is de omzetter niet die informatie verliest — het is de vorm die echt verandert — maar het vooraf weten bespaart je van een grote diff lezen als een grote wijziging.

Prefixen blijven onderdeel van de sleutelnaam, dus levert een document met soap: of xsi: sleutels op met een dubbele punt erin. De schrijver geeft die zonder aanhalingstekens uit, en ze lezen correct terug via dezelfde parser. De namespace-declaraties zelf overleven als attributen, dus komt een standaard xmlns aan als een aangehaalde "@xmlns"-sleutel op de root.

Een dubbele punt in een niet-aangehaalde sleutel is het soort dat de moeite waard is om met de hand aan te scherpen voor het bestand reist. Gaat de YAML door een ander gereedschap gelezen worden, haal die sleutels dan zelf aan — het kost niets en neemt een klasse problemen weg die alleen opduikt op het punt waar iemand anders het bestand parseert. Niets lost prefixen op naar hun namespace-URI’s, dus produceren twee documenten met verschillende prefixen voor dezelfde namespace YAML die niet netjes tegen elkaar diffen.

Waarden die als getallen lezen, worden geparseerd, zowel in elementtekst als in attributen. Een Maven-versie van 4.13.2 blijft tekst, want die heeft twee punten en kan geen getal zijn, en zo ook een adres of een pad. Een version-attribuut geschreven als 1.0 wordt 1, en een met nullen opgevulde waarde geschreven als 007 wordt 7.

Op een config die gelezen wordt in plaats van uitgevoerd is de schade beperkt tot hoe de waarde eruitziet, en het doet er nog steeds toe: een schemaversie weergegeven als 1 in plaats van 1.0 in een review is een waarde waar iemand aan gaat twijfelen of erger, kopiëren. Scan de getal-ogende waarden in de uitvoer eenmaal. Gaat de YAML ergens anders heen dan een menselijk oog, haal dan de aan die als identifiers bedoeld waren.

Een waarde met nieuwe regels wordt geschreven als een blokscalar — een verticale streep met de tekst eronder ingesprongen — wat het leesbaar houdt in plaats van hem op één regel te ontsnappen. Een lange waarde op één regel wordt zoals hij is geschreven, zonder afbreken. Beide zijn de juiste keuze voor een bestand bedoeld om gelezen te worden.

Een leeg of zelfsluitend element wordt een lege tekst, geschreven als een paar aanhalingstekens. XML maakt geen onderscheid tussen een leeg element en een dat niets bevat, dus gaat er geen informatie verloren, maar een lege tekst is visueel makkelijk te missen in een lang bestand — controleer je een config op niet-ingestelde waarden, zoek dan naar de lege aanhalingstekens in plaats van op het oog te vertrouwen.

XML ondersteunt opmerkingen, YAML ondersteunt opmerkingen, en geen van de jouwe overleeft. De parser gooit ze weg en niets schrijft ze terug. Bij een payload maakt dat niet uit; bij een buildbestand is het het grootste verlies, want de opmerking boven een vastgepinde afhankelijkheidsversie is meestal de enige overgebleven verklaring waarom die vastgepind is.

De werkende regeling die de valkuil vermijdt, is de YAML als leeskopie te behandelen en de XML als bron te bewaren. Wordt de YAML in plaats daarvan de bron — een echte migratie naar Ansible of een Helm-chart — plan dan de stap die de opmerkingen overzet als onderdeel van het werk, voor de XML verwijderd wordt en de redenering ermee verdwijnt.

Een omgezette config is nog geen values-bestand of variabelenset. Hij draagt XML-artefacten — de @-sleutels, de #text-sleutels, een namespace-declaratie op de root, en mogelijk een ?xml-sleutel van de declaratieregel — die betekenisloos zijn voor wat je ook voedt. Ze verwijderen is de eerste ronde.

De tweede is benoemen. XML-elementnamen zijn vaak uitgebreid op een manier die logisch was met een schema erachter, en een YAML-config wil ze meestal korter en platter. Beide rondes zijn handmatig en beide zijn de echte migratie; de omzetting geeft je alleen een leesbaar startpunt in plaats van een muur tags.

Zet om als het doel is te begrijpen, te beoordelen of te vergelijken: de YAML is korter, de structuur is duidelijk, en het geheel draait in je browser in de tijd die het kost het bestand te slepen. Het is een goede gewoonte voor elke config die je krijgt en waarover je moet nadenken voor je iets verandert.

Zet niet om als het bestand door een schema wordt gevalideerd, ondertekend is, of door een gereedschap wordt geconsumeerd dat XML leest. De XML is in dat geval het artefact, en een YAML-kopie is een tweede versie van de waarheid die van de eerste zal afwijken. Lees hem als YAML, wijzig hem als XML.