Converting JSON to XML sounds straightforward since both are hierarchical data formats. But the type systems are different enough that edge cases arise constantly. This guide covers every important scenario with examples.

Why Convert JSON to XML?

• Legacy SOAP APIs: Many enterprise systems (banking, ERP, insurance) expose only SOAP/XML endpoints.
• Android resources: Android app resources (strings.xml, layout XML) are XML-based.
• RSS and Atom feeds: Both feed formats are XML standards.
• Document management systems: Many ECM platforms store content as XML.
• Microsoft Office formats: DOCX and XLSX are ZIP archives containing XML files.

The Basic Mapping Rules

The straightforward cases map cleanly:

• JSON object → XML element containing child elements (one child per key)
• JSON string/number/boolean → XML text node
• JSON null → empty XML element or omitted element (convention varies)
• JSON array → repeated sibling elements with the same tag name

{
  "person": {
    "name": "Alice",
    "age": 30,
    "active": true
  }
}

Becomes:

<?xml version="1.0" encoding="UTF-8"?>
<person>
  <name>Alice</name>
  <age>30</age>
  <active>true</active>
</person>

Edge Case 1: The Root Element Problem

XML documents must have exactly one root element. A JSON object with multiple top-level keys does not have an obvious single root, and a JSON array has no root at all.

// This JSON array has no natural root element
[
  { "id": 1, "name": "Alice" },
  { "id": 2, "name": "Bob" }
]

Most converters wrap the array in a generic root element:

<?xml version="1.0" encoding="UTF-8"?>
<root>
  <item>
    <id>1</id>
    <name>Alice</name>
  </item>
  <item>
    <id>2</id>
    <name>Bob</name>
  </item>
</root>

Edge Case 2: Array Handling, Repeated vs. Wrapped

There are two conventions for how JSON arrays map to XML. Consider:

{ "tags": ["developer", "admin", "editor"] }

Option A: Repeated elements (each array item gets the parent key as its tag):

<tags>developer</tags>
<tags>admin</tags>
<tags>editor</tags>

Option B: Wrapper + item element:

<tags>
  <item>developer</item>
  <item>admin</item>
  <item>editor</item>
</tags>

Option A is more common and makes round-tripping (XML back to JSON) easier. Option B is preferred when the target XML schema requires a wrapping element.

Edge Case 3: Special XML Characters

XML has five reserved characters that must be escaped as XML entities when they appear in text content:

& → &
< → &lt;
> → &gt;
" → &quot;  (in attribute values)
' → &apos;  (in attribute values)

{ "expression": "a < b && c > d" }

Must become:

<expression>a &lt; b &amp;&amp; c &gt; d</expression>

Edge Case 4: Invalid XML Element Names

XML element names must start with a letter or underscore and contain only letters, digits, hyphens, underscores, and periods. JSON keys have no such restrictions. Common problematic JSON keys include:

{
  "123abc": "starts with digit",
  "my-key": "hyphens ok in XML, but check your XPath",
  "my key": "spaces not allowed in XML names",
  "@type": "at-sign not allowed"
}

Converters typically handle these by prefixing invalid names with an underscore (`_123abc`, `_type`) or by URL-encoding the key. The exact strategy should match what the XML consumer expects.

Edge Case 5: Null Values

JSON `null` has no direct XML equivalent. There are two conventions:

• Omit the element entirely: `{ "middle_name": null }` → element not included in output
• Empty element with an xsi:nil attribute (XML Schema convention): `<middle_name xsi:nil="true"/>`

If you are targeting a SOAP service with an XSD schema, use `xsi:nil`. If you are generating XML for general consumption, omitting null elements is usually cleaner.