YAML naar XML omzetten

Elke sleutel wordt een element en zijn waarde wordt de inhoud van dat element. Een geneste mapping wordt een genest element, ingesprongen met twee spaties per niveau, en een scalar wordt tekst tussen een openings- en sluittag. Niets aan de doorloop is slim, wat precies de eigenschap is die je wilt als de uitvoer moet matchen met een specificatie die iemand anders schreef.

Waarden worden als tekst geschreven, want dat is alles wat een XML-element kan bevatten. Een YAML-getal geschreven als 1.50 komt eruit als 1.5, want de parser loste het al op naar een getal voordat de schrijver het zag, en een boolean komt eruit als het woord true of false. Is het ontvangende schema strikt over de lexicale vorm — een decimaal dat zijn nul aan het eind moet houden, een datum die een tijdzone moet dragen — dan moet de waarde als tekenreeks aangehaald worden in de YAML zodat hij letterlijk overleeft.

XML vereist precies één buitenste element en een YAML-document kan meerdere sleutels op het hoogste niveau hebben. De regel is: één sleutel op het hoogste niveau wordt het hoofdelement, wat hij ook bevat, tenzij hij een lijst bevat. Zo levert een document met alleen de sleutel order een order-hoofdelement op; net als eentje met alleen de sleutel title met een scalar eronder, wat het eenregelige document <title>hallo</title> geeft. Een document met drie sleutels op het hoogste niveau levert een generiek hoofdelement met drie kinderen op.

Eén sleutel op het hoogste niveau met een lijst erin is het geval dat mensen verrast. Die krijgt ook de generieke omwikkeling, want de sleutel als hoofdelement gebruiken zou die tag eenmaal per item herhalen en een document met meerdere buitenste elementen achterlaten, wat helemaal geen XML is. Doet de naam van het hoofdelement ertoe — en in een integratie doet die dat altijd — geef de YAML dan één mapping-sleutel op het hoogste niveau die exact heet wat het schema verwacht, en zet er alles onder.

Een YAML-sequence onder een sleutel geeft die sleutel eenmaal per item uit. Drie build-opdrachten onder een sleutel script worden drie script-elementen op volgorde, zusters van elkaar. Dit is het oudere en gangbaardere XML-idioom, en het is wat een XSD geschreven met maxOccurs unbounded verwacht.

Het is niet het enige idioom. Veel schema's willen een meervoudsomwikkeling met enkelvoudige kinderen erin — een dependencies-element met verschillende dependency-elementen erin — en deze schrijver produceert dat niet uit een gewone lijst. Je krijgt het door de YAML zo te schrijven: een sleutel genaamd dependencies wiens waarde een mapping is met één sleutel genaamd dependency die de lijst draagt. De nesting in de bron produceert de nesting in de uitvoer, dus vorm de YAML naar het schema in plaats van te verwachten dat de converter raadt.

XML met alleen elementen is prima voor data en fout voor de meeste echte schema's, die identifiers, typen en taalcodes in attributen zetten. Twee sleutelnamen geven je controle. Een sleutel wiens naam begint met @ wordt een attribuut op het omsluitende element met de @ verwijderd, en een sleutel genaamd #text wordt de eigen tekstinhoud van het element.

Uitgeschreven produceert een YAML-mapping genaamd order met "@id" op 42, "@status" op open, en een customer-sleutel een order-element met id- en status-attributen en een customer-kind erin. "@lang" en "#text" combineren in één mapping geeft één tag met een attribuut en tekst en geen kinderen. Beide sleutels moeten in de YAML aangehaald worden, want @ aan het begin van een gewone scalar is gereserveerd en # zou commentaar beginnen.

XML-elementnamen staan letters, cijfers, underscores, koppeltekens en punten toe, en mogen niet met een cijfer beginnen. YAML-sleutels staan vrijwel alles toe. Elk teken dat de schrijver niet kan gebruiken wordt een underscore, en een naam die met een cijfer begint krijgt er een voorvoegsel — dus wordt "my key" my_key en "2nd" wordt _2nd.

De vervanging verliest informatie en kan botsen: twee sleutels die alleen verschillen in welk verboden teken ze bevatten, eindigen als dezelfde elementnaam. Koppeltekens en punten gaan er onaangeroerd doorheen, dus wordt een sleutel als build-job of tool.ruff geschreven zoals je hem typte. Noemt het doelschema de elementen, hernoem dan de YAML-sleutels om te matchen voordat je omzet in plaats van de XML achteraf te repareren.

Er is geen XML-declaratie, dus begint het bestand met de eerste tag. Er is geen DOCTYPE, geen naamruimteverklaring en geen schemaverwijzing. De uitvoer is UTF-8 en welgevormd, en niets erin zegt tot welke woordenschat hij behoort.

Voor een integratie is dat meestal een gat om met de hand te dichten, en het is een klein gat: een declaratieregel, een xmlns-attribuut op het hoofdelement, en een schemalocatie. Het xmlns-attribuut is makkelijk toe te voegen aan de bron, want het is gewoon nog een sleutel die met @ begint in de mapping op het hoogste niveau van de YAML — wat betekent dat de naamruimte elke toekomstige omzetting overleeft in plaats van steeds opnieuw toegevoegd te worden.

Een YAML-sleutel zonder waarde wordt een leeg elementenpaar. XML kan dat niet onderscheiden van een element met een lege tekenreeks erin, dus als het schema afwezig en leeg verschillend behandelt, laat de sleutel dan uit de YAML weg in plaats van hem er met niets erna in te zetten.

Ampersands, punthaken en dubbele aanhalingstekens in een waarde worden geëscapet, dus komt tekst met een URL met queryparameters of een stukje code veilig door in plaats van het document te breken. Een blokscalar over meerdere regels wordt geschreven met zijn regeleindes intact binnen het element, wat geldige XML is — maar of de ontvangende parser die witruimte bewaart hangt af van het schema, dus alles dat gevoelig is voor witruimte hoort in een CDATA-sectie die je zelf toevoegt.

XML is sinds 1998 een W3C-aanbeveling, en de reden om het te schrijven in plaats van JSON is bijna altijd het ecosysteem eerder dan de syntaxis: XSD om een misvormd document af te wijzen voordat het een toepassing bereikt, XPath om één waarde uit een groot document te halen, XSLT om het te herschikken, en XML digitale handtekeningen waar een tegenpartij moet bewijzen dat een document niet gewijzigd is.

Niets daarvan komt gratis met de omzetting. Draai de uitvoer meteen tegen het schema, op het eerste bestand, voordat je het proces opzet — een element dat een attribuut had moeten zijn is een wijziging van twee tekens in de YAML en een lange middag als je het vindt nadat je een pijplijn om de verkeerde vorm heen gebouwd hebt.

Twee bronproblemen stoppen de omzetting in plaats van hem te verslechteren. Een bestand met ---scheidingstekens draagt meerdere YAML-documenten, en een XML-bestand draagt er één, dus weigert de parser in plaats van te kiezen. Splits het en zet elk document apart om. Een dubbele sleutel in dezelfde mapping wordt ook geweigerd, met het regelnummer, wat strikter is dan sommige YAML-gereedschappen en correct — een gedupliceerde sleutel betekent dat een van de twee instellingen genegeerd is sinds de dag dat hij is toegevoegd.

Commentaar stopt niets en overleeft ook niet. Beide formaten ondersteunen het en geen van het jouwe gaat mee, dus draagt de XML die je oplevert de data en niets van de redenering. Houd de YAML als de bron van waarheid, genereer de XML als een artefact, en bewerk de XML nooit — dat is de werkwijze waar deze omzetting voor gebouwd is.