Convert YAML to XML

Each key becomes an element and its value becomes the content of that element. A nested mapping becomes a nested element, indented two spaces per level, and a scalar becomes text between an opening and a closing tag. Nothing about the traversal is clever, which is the property you want when the output has to match a specification somebody else wrote.

Values are written as text, because that is all an XML element can hold. A YAML number written 1.50 comes out as 1.5, since the parser resolved it to a number before the writer saw it, and a boolean comes out as the word true or false. If the receiving schema is strict about lexical form — a decimal that must keep its trailing zero, a date that must carry a timezone — the value has to be quoted as a string in the YAML so it survives verbatim.

XML requires exactly one outermost element and a YAML document can have several top-level keys. The rule is: one top-level key becomes the root, whatever it holds, unless what it holds is a list. So a document whose only key is order produces an order root; so does one whose only key is title with a scalar under it, giving the single-line document <title>hello</title>. A document with three top-level keys produces a generic root containing three children.

A single top-level key holding a list is the case that surprises people. It also gets the generic wrapper, because using the key as the root would repeat that tag once per item and leave a document with several outermost elements, which is not XML at all. If the root element name matters — and in an integration it always does — give the YAML one top-level mapping key named exactly what the schema expects, and put everything under it.

A YAML sequence under a key emits that key once per item. Three build commands under a script key become three script elements in order, siblings of each other. This is the older and more common XML idiom, and it is what an XSD written with maxOccurs unbounded expects.

It is not the only idiom. Plenty of schemas want a plural wrapper containing singular children — a dependencies element holding several dependency elements — and this writer will not produce that from a plain list. You get it by writing the YAML that way: a key named dependencies whose value is a mapping with one key named dependency holding the list. The nesting in the source is what produces the nesting in the output, so shape the YAML to the schema rather than expecting the converter to guess.

Elements-only XML is fine for data and wrong for most real schemas, which put identifiers, types and language codes in attributes. Two key names give you control. A key whose name starts with @ becomes an attribute on the enclosing element with the @ stripped, and a key named #text becomes the element own text content.

Written out, a YAML mapping named order containing "@id" set to 42, "@status" set to open, and a customer key produces an order element carrying id and status attributes with a customer child inside it. Combining "@lang" and "#text" in one mapping produces a single tag with an attribute and text and no children. Both keys need quoting in the YAML, since @ at the start of a plain scalar is reserved and # would start a comment.

XML element names allow letters, digits, underscores, hyphens and dots, and may not begin with a digit. YAML keys allow essentially anything. Every character the writer cannot use becomes an underscore, and a name starting with a digit is prefixed with one, so "my key" becomes my_key and "2nd" becomes _2nd.

The substitution loses information and can collide: two keys differing only in which forbidden character they contain end up as the same element name. Hyphens and dots pass through untouched, so a key like build-job or tool.ruff is written as you typed it. If the target schema names the elements, rename the YAML keys to match before converting rather than repairing the XML afterwards.

There is no XML declaration, so the file starts with the first tag. There is no DOCTYPE, no namespace declaration and no schema reference. The output is UTF-8 and well-formed, and nothing in it says which vocabulary it belongs to.

For an integration that is usually a gap to close by hand, and it is a small one: a declaration line, an xmlns attribute on the root, and a schema location. The xmlns attribute is easy to add at the source, since it is just another key beginning with @ in the top-level mapping of the YAML — which means the namespace survives every future conversion instead of being re-added each time.

A YAML key with no value becomes an empty element pair. XML cannot distinguish that from an element containing an empty string, so if the schema treats absent and empty differently, leave the key out of the YAML rather than writing it with nothing after it.

Ampersands, angle brackets and double quotes in a value are escaped, so text containing a URL with query parameters or a fragment of code comes through safely rather than breaking the document. A multi-line block scalar is written with its newlines intact inside the element, which is valid XML — but whether the receiving parser preserves that whitespace depends on the schema, so anything whitespace-sensitive belongs in a CDATA section that you add yourself.

XML has been a W3C recommendation since 1998, and the reason to emit it rather than JSON is almost always the ecosystem rather than the syntax: XSD to reject a malformed document before it reaches an application, XPath to pull one value out of a large one, XSLT to reshape it, and XML digital signatures where a counterpart needs to prove a document was not altered.

None of it comes for free with the conversion. Run the output against the schema immediately, on the first file, before wiring the process up — an element that should have been an attribute is a two-character change in the YAML and a long afternoon if you find it after building a pipeline around the wrong shape.

Two source problems stop the conversion rather than degrading it. A file containing --- separators holds several YAML documents, and an XML file holds one, so the parser refuses instead of choosing. Split it and convert each document. A duplicate key in the same mapping is also rejected, with the line number, which is stricter than some YAML tooling and correct — a duplicated key means one of the two settings has been ignored since the day it was added.

Comments do not stop anything and do not survive either. Both formats support them and none of yours cross over, so the XML you deliver carries the data and none of the reasoning. Keep the YAML as the source of truth, generate the XML as an artefact, and never edit the XML — that is the working arrangement this conversion is built for.