JSON vs YAML vs XML: differences, trade-offs and conversion pitfalls

Before converting a configuration file or API response, find out what the receiving system expects. A successful conversion means the output was produced; it does not mean the new file has the right structure or keeps every detail of the original.

Keep a copy of the source, convert a representative sample, and inspect the fields that matter: identifiers, lists, attributes, text and comments. Those checks are especially important when moving XML into JSON.

Choose for the data and the receiving system

JSON represents objects, arrays, strings, numbers, booleans and null. It suits structured data exchanged between programs. Standard JSON has no comment syntax; validation schemas are separate from the JSON document.

YAML supports mappings, sequences and scalar values, with comments and additional features such as anchors and tags. It can be convenient for configuration edited by people, provided the application agrees on the YAML version and supported features.

XML represents documents using elements, attributes and namespaces, and can preserve text interleaved with markup. It is useful when those document features matter or an integration specifies an XML schema.

All three can carry useful structured data. The receiver’s contract matters more than a general preference for one format.

XML attributes need a mapping convention

An XML element can have both an attribute and text:

<item code="A7">Widget</item>

With the data format converter’s default options, its JSON representation is:

{
  "item": {
    "#text": "Widget",
    "@code": "A7"
  }
}

The @ attribute prefix and #text key are this converter’s convention, not universal JSON meanings. XML options lets you change both, set a root element name and choose whether to keep namespace prefixes. The system consuming the result must understand the same convention.

One XML child does not automatically become an array

Compare these two conversions with the current defaults:

<list><item>a</item></list>
→ {"list":{"item":"a"}}

<list><item>a</item><item>b</item></list>
→ {"list":{"item":["a","b"]}}

The single item becomes a string; repeated item elements become an array. A consumer expecting an array in both cases needs a normalisation step or a schema-aware mapping. The local interface does not offer an “always array for this element” setting.

Test empty, single-item and multiple-item cases. A sample with two items alone will not reveal this difference.

Keep identifiers as strings

In YAML, quote a value when its spelling must be retained:

country: "NO"
enabled: true
code: "007"

YAML 1.1 and YAML 1.2 core-schema rules differ: words such as NO and on could be booleans under 1.1, while the local parser treats them as strings under its current defaults. Quoting documents your intended type.

XML also needs care. The local converter infers numbers in text and attributes. <item code="007">01</item> becomes an item with @code: 7 and #text: 1. Attribute quotes are XML syntax; they do not tell this converter to preserve the value as a JSON string. The interface currently has no switch to disable this inference.

Large integers need a separate precision check. Parsing JSON into JavaScript numbers can round integers beyond its exact integer range. Identifiers that must retain every digit should be strings in the agreed data format.

Comments and document structure can disappear

Both YAML and XML support comments. This converter parses into data values and does not preserve those comments, even when converting YAML back to YAML. Anchor names, formatting and original quote style are also not a round-trip guarantee.

XML mixed content is another case where a data-object mapping loses information. For <p>Hello <b>friend</b>!</p>, the current converter produces a b value of friend and a #text value of Hello!. The placement of text around the child element is no longer represented.

Keeping namespace prefixes retains names such as x:item, but does not give a JSON consumer XML namespace semantics. If order, whitespace or namespaces affect meaning, use a conversion designed for that document model rather than assuming this general-purpose mapping is lossless.

Check entities and parser limits

The local XML parser is configured with entity processing disabled. For example, <name>Tom &amp; Ada</name> currently yields the literal string Tom & Ada, not Tom & Ada. Check entity-containing text before sending the converted result to another system.

The installed parser rejects external entity declarations. It does not reject every internal entity declaration; internal references can remain unexpanded. This is narrower than a claim that all XML entity constructs are refused.

The YAML parser does not instantiate executable language objects from tags such as !!js/function in this setup. That does not make every YAML parser safe by default. Large inputs, deeply nested data and downstream use of values require care in any of these formats, including JSON.

Review the output where it will be used

Check that counts and types agree with the receiving schema, then test the converted sample in that application. A conversion back to the source format can expose losses, but a clean-looking round trip alone does not establish compatibility.

For JSON formatting without a format change, use the JSON formatter. For a table of records, the JSON–CSV tool may be the relevant conversion; nested structures still need an agreed representation.

Sources and further reading

• RFC 8259 — JSON, including number interoperability
• YAML 1.2.2 specification — schemas and tag resolution
• W3C XML 1.0 — document structure, comments and entities
• OWASP — XML External Entity Prevention
• fast-xml-parser — implementation documentation

Last reviewed 2 October 2026.