YAML to XML Converter

Converting YAML to XML is the direction people take when a modern config has to feed an older consumer: an enterprise integration bus that only accepts XML, a SOAP endpoint, a reporting tool built around XSLT, or a Java application whose configuration loader predates the YAML era. The data is already in the shape you want; it is the notation that has to change.

Two structural mismatches decide the output. XML permits exactly one root element, while a YAML mapping can have any number of top-level keys and a YAML stream can hold several documents. And XML element names are constrained — they cannot begin with a digit or contain spaces — while YAML keys can be almost anything, including numbers and booleans. Both are handled explicitly and described below. Everything runs in your browser in a Web Worker.

How your YAML is reshaped

The YAML is parsed into a data model and that model is serialised as XML. The rules that matter:

• One top-level key becomes the root element. A YAML file whose entire content sits under a single key converts to XML with that key as the root and no artificial wrapper. This gives the cleanest output, so it is worth restructuring for.
• Several top-level keys are wrapped in <root>. The workflow file in the example has name, on, env and jobs at the top level, so all four become children of a synthetic root. XML has no way to express four peers at the document level.
• Sequences become repeated elements. A list under steps: becomes several <steps> elements side by side, which is the conventional XML idiom for a collection. There is no <steps><step/></steps> wrapper unless your YAML already nests that way.
• Scalars become text content. Numbers, booleans and dates all become their text representation, because XML text is untyped. enabled: true becomes <enabled>true</enabled>, and a consumer has to know from a schema that it should be read as a boolean.
• Null becomes an empty element. A YAML key with no value, or an explicit ~, produces <key/>. The difference between null and the empty string is not preserved.
• A key beginning with @ becomes an attribute and a key named #text becomes element text. That is the convention the XML to YAML tool emits, so the pair round-trips.
• Reserved characters are escaped. Ampersands and angle brackets in your values are converted to entities automatically; you never need to pre-escape.

Keys that XML cannot name

XML element names must start with a letter or underscore and may then contain letters, digits, hyphens, full stops, underscores and colons. YAML keys have no such restriction, and real config files break the rules constantly.

Any key that is not a valid name is repaired: it gets an underscore prefix if needed, and each remaining illegal character is replaced with an underscore. timeout minutes becomes <timeout_minutes>, and a numeric key such as 2024 becomes <_2024>. Numeric keys are common in YAML — port maps, year-indexed data, HTTP status code tables — so expect to see this.

Two caveats. First, sanitisation can collide: on push and on-push both become on_push, and nothing warns you. Second, a key that YAML parsed as a boolean is stringified before it becomes an element name, which is why the GitHub Actions on: key is worth watching — under a YAML 1.1 parser it would have become the boolean true, though the YAML 1.2 parser used here keeps it as the string on.

If element names are contractual — because a schema or an XSLT stylesheet depends on them — check every name in the output rather than assuming the mapping was clean.

What is lost on the way through

Comments disappear. YAML comments carry no structural information and there is nothing in the data model to hold them, so they cannot be re-emitted as XML comments. Copy any that matter across by hand.

Anchors and aliases are expanded, not preserved. A block defined once with &defaults and referenced three times appears three times in full in the XML. The data is right and the file is bigger.

A multi-document stream is flattened. Because a stream parses to a list of documents and XML wants a single root, several documents end up as repeated child elements inside the synthetic root rather than as separate XML documents. If you need one XML document per YAML document, split the stream before converting.

No namespaces are generated. If the consuming system needs them, add an "@xmlns" key to the mapping that becomes your root before converting, and it will be emitted as a declaration on the root element. Likewise, the output will not validate against any particular XSD without deliberate shaping — well-formed is not the same as valid.