XML to JSON Conversion: Handling the Tricky Parts

March 31, 2026 · 12 min read

Understanding XML to JSON Conversion Complexity

In the world of data exchange, it's almost impossible to avoid XML and JSON. XML is like that bulky toolbox that can handle a wide range of tasks, from simple tags to intricate structures incorporating attributes and namespaces. JSON, meanwhile, is more like a tidy note-taking app: straightforward key-value pairs.

Thanks to these contrasts, flipping XML into JSON can get tricky. It's not just about making things look similar, but ensuring all the vital info stays intact during the shift. The fundamental challenge lies in the fact that XML and JSON have different structural philosophies—XML is document-oriented while JSON is data-oriented.

Take complexity, for example. XML can craft deeply nested structures, like the intricate branches of a family tree—parents, children, grandchildren, way down. When converting to JSON, it's critical to navigate this nesting without skipping any branches or data bits.

Consider an organization like Acme Corp, which uses XML to keep track of its intricate reporting structure. There's a 'CEO' at the top, followed by 'Vice Presidents', then 'Department Heads', and finally 'Team Leads'. Each XML tag represents these layers.

When converting this to JSON, it's necessary to ensure that the hierarchy doesn't collapse and information remains accessible. This preservation allows business analysts to perform queries across departments without losing sight of relationships. A poorly executed conversion might flatten the structure or lose parent-child relationships entirely.

The structural differences become even more apparent when dealing with document-centric XML versus data-centric XML. Document-centric XML (like XHTML or DocBook) contains mixed content with text interspersed with markup. Data-centric XML (like configuration files or API responses) has a more predictable structure that maps more cleanly to JSON.

Why Direct Conversion Isn't Always Straightforward

Many developers assume they can simply parse XML and output JSON with a one-to-one mapping. This approach works for simple cases but breaks down quickly when encountering:

• Attributes mixed with child elements
• Repeated elements that should become arrays
• Namespace prefixes that need preservation
• CDATA sections and processing instructions
• Comments that may contain important metadata
• Entity references and character encoding issues

Each of these scenarios requires careful consideration and often custom handling logic. There's no universal standard for XML to JSON conversion, which means different tools and libraries may produce different results from the same input.

Handling XML Attributes in JSON

XML attributes present one of the most significant challenges in XML to JSON conversion. In XML, attributes provide metadata about elements, but JSON has no native concept of attributes—everything is either an object property or an array element.

Consider this simple XML snippet:

<person id="12345" status="active">
  <name>Jane Smith</name>
  <email>[email protected]</email>
</person>

There are several common approaches to representing this in JSON, each with trade-offs:

Convention-Based Approaches

The @ Prefix Convention: This is one of the most popular approaches, where attributes are prefixed with an @ symbol:

{
  "person": {
    "@id": "12345",
    "@status": "active",
    "name": "Jane Smith",
    "email": "[email protected]"
  }
}

This approach is widely used by libraries like xml2js and maintains a clear distinction between attributes and child elements. However, it introduces non-standard JSON keys that may confuse consumers unfamiliar with the convention.

The Nested Attributes Object: Another approach groups all attributes into a dedicated object:

{
  "person": {
    "attributes": {
      "id": "12345",
      "status": "active"
    },
    "name": "Jane Smith",
    "email": "[email protected]"
  }
}

This method keeps attributes clearly separated but adds an extra layer of nesting that can make data access more verbose.

Flattening Attributes: Some converters simply treat attributes as regular properties:

{
  "person": {
    "id": "12345",
    "status": "active",
    "name": "Jane Smith",
    "email": "[email protected]"
  }
}

This produces the cleanest JSON but loses the semantic distinction between attributes and elements. If an element and attribute share the same name, you'll face naming conflicts.

Real-World Attribute Handling Example

Let's look at a more complex scenario from an e-commerce system where product data includes multiple attributes:

<product id="SKU-9876" category="electronics" inStock="true">
  <name lang="en">Wireless Headphones</name>
  <price currency="USD">79.99</price>
  <dimensions unit="cm">
    <width>15</width>
    <height>18</height>
    <depth>7</depth>
  </dimensions>
</product>

Using the @ prefix convention with proper type handling:

{
  "product": {
    "@id": "SKU-9876",
    "@category": "electronics",
    "@inStock": true,
    "name": {
      "@lang": "en",
      "#text": "Wireless Headphones"
    },
    "price": {
      "@currency": "USD",
      "#text": 79.99
    },
    "dimensions": {
      "@unit": "cm",
      "width": 15,
      "height": 18,
      "depth": 7
    }
  }
}

Notice how elements with both attributes and text content use #text to hold the actual value. This is another common convention that prevents ambiguity.

Managing Arrays and Single Elements

One of the most frustrating aspects of XML to JSON conversion is the array ambiguity problem. In XML, there's no syntactic difference between a single element and a collection of elements. JSON, however, makes a clear distinction between objects and arrays.

Consider this XML representing a shopping cart:

<cart>
  <item>Laptop</item>
</cart>

A naive converter might produce:

{
  "cart": {
    "item": "Laptop"
  }
}

But what happens when the cart has multiple items?

<cart>
  <item>Laptop</item>
  <item>Mouse</item>
  <item>Keyboard</item>
</cart>

Now the converter produces:

{
  "cart": {
    "item": ["Laptop", "Mouse", "Keyboard"]
  }
}

This inconsistency is a nightmare for consuming applications. Code that expects cart.item to be a string will break when it suddenly becomes an array. Code that expects an array will fail when there's only one item.

Solutions to the Array Problem

Always Use Arrays: The safest approach is to always represent repeatable elements as arrays, even when there's only one item:

{
  "cart": {
    "item": ["Laptop"]
  }
}

This ensures consistency but produces slightly more verbose JSON. Most modern JSON consumers can handle this easily with array iteration that works for both single and multiple items.

Schema-Driven Conversion: If you have an XML Schema (XSD) or DTD, you can use it to determine which elements should always be arrays. Elements with maxOccurs > 1 in the schema should always convert to arrays.

Heuristic Detection: Some converters analyze the entire XML document before conversion to detect which elements appear multiple times, then consistently use arrays for those elements throughout the document.

Configuration Options: Many conversion libraries let you specify which elements should always be arrays:

// Example configuration for xml2js
const options = {
  explicitArray: true,  // Always use arrays
  arrayElements: ['item', 'product', 'order']  // Specific elements
};

Practical Example: Order Processing System

Here's a real-world example from an order processing system that demonstrates proper array handling:

<order id="ORD-2024-001">
  <customer>John Doe</customer>
  <items>
    <item sku="WIDGET-A" quantity="2">
      <name>Premium Widget</name>
      <price>29.99</price>
    </item>
    <item sku="GADGET-B" quantity="1">
      <name>Super Gadget</name>
      <price>49.99</price>
    </item>
  </items>
  <shippingAddress>
    <street>123 Main St</street>
    <city>Springfield</city>
  </shippingAddress>
</order>

Proper conversion with consistent array handling:

{
  "order": {
    "@id": "ORD-2024-001",
    "customer": "John Doe",
    "items": {
      "item": [
        {
          "@sku": "WIDGET-A",
          "@quantity": 2,
          "name": "Premium Widget",
          "price": 29.99
        },
        {
          "@sku": "GADGET-B",
          "@quantity": 1,
          "name": "Super Gadget",
          "price": 49.99
        }
      ]
    },
    "shippingAddress": {
      "street": "123 Main St",
      "city": "Springfield"
    }
  }
}

Notice that item is always an array, while customer and shippingAddress are singular objects. This reflects the semantic meaning: an order can have multiple items but only one customer and one shipping address.

Dealing with XML Namespaces

XML namespaces are a powerful feature for avoiding naming conflicts, especially when combining XML from different sources. However, they add significant complexity to JSON conversion because JSON has no native namespace concept.

Consider this XML with namespaces:

<root xmlns:prod="http://example.com/products" 
      xmlns:inv="http://example.com/inventory">
  <prod:product>
    <prod:name>Widget</prod:name>
    <inv:quantity>100</inv:quantity>
  </prod:product>
</root>

Namespace Handling Strategies

Preserve Prefixes: The simplest approach keeps namespace prefixes in the JSON keys:

{
  "root": {
    "prod:product": {
      "prod:name": "Widget",
      "inv:quantity": 100
    }
  }
}

This works but creates keys with colons, which can be problematic in some programming languages where dot notation is used to access object properties.

Expand to Full URIs: Replace prefixes with full namespace URIs:

{
  "root": {
    "{http://example.com/products}product": {
      "{http://example.com/products}name": "Widget",
      "{http://example.com/inventory}quantity": 100
    }
  }
}

This is unambiguous but produces very verbose keys that are cumbersome to work with.

Strip Namespaces: Remove namespace information entirely:

{
  "root": {
    "product": {
      "name": "Widget",
      "quantity": 100
    }
  }
}

This produces clean JSON but loses important semantic information and can cause naming conflicts if different namespaces use the same element names.

Nested Namespace Objects: Group elements by namespace:

{
  "root": {
    "prod": {
      "product": {
        "name": "Widget"
      }
    },
    "inv": {
      "quantity": 100
    }
  }
}

This preserves namespace information while keeping keys clean, but it changes the document structure significantly.

Default Namespace Handling

Default namespaces (declared with xmlns="..." without a prefix) present an additional challenge:

<product xmlns="http://example.com/products">
  <name>Widget</name>
  <price>19.99</price>
</product>

Since there's no prefix, you need to decide how to represent the namespace in JSON. Common approaches include using a special prefix like _default or simply stripping the default namespace while preserving explicit prefixes.

Addressing Special XML Constructs

XML includes several special constructs that have no direct JSON equivalent. Handling these properly is essential for accurate conversion.

CDATA Sections

CDATA sections allow you to include text that contains characters that would otherwise be interpreted as markup:

<description>
  <![CDATA[This product costs <$50 and is >90% effective!]]>
</description>

Most converters simply extract the text content:

{
  "description": "This product costs <$50 and is >90% effective!"
}

This works for most use cases, but if you need to preserve the fact that content was in a CDATA section (for round-trip conversion), you might use a special marker:

{
  "description": {
    "#cdata": "This product costs <$50 and is >90% effective!"
  }
}

Processing Instructions

Processing instructions provide directives to applications processing the XML:

<?xml-stylesheet type="text/xsl" href="style.xsl"?>
<document>
  <content>Hello World</content>
</document>

These are typically stripped during conversion since they're XML-specific. If you need to preserve them, you can include them in a special metadata section:

{
  "_processing_instructions": [
    {
      "target": "xml-stylesheet",
      "data": "type=\"text/xsl\" href=\"style.xsl\""
    }
  ],
  "document": {
    "content": "Hello World"
  }
}

Comments

XML comments can contain important documentation or metadata:

<config>
  <!-- Production settings -->
  <database>prod-db.example.com</database>
  <!-- Updated 2024-03-15 -->
  <timeout>30</timeout>
</config>

Most converters discard comments by default. If you need to preserve them:

{
  "config": {
    "_comments": [
      "Production settings",
      "Updated 2024-03-15"
    ],
    "database": "prod-db.example.com",
    "timeout": 30
  }
}

Entity References

XML supports entity references for special characters and reusable content:

<text>Price: &lt; $100 &amp; free shipping</text>

Standard entity references (<, >, &, ", ') are automatically resolved during parsing:

{
  "text": "Price: < $100 & free shipping"
}

Custom entity references defined in a DTD require special handling and may need to be resolved before conversion or preserved in a special format.

Empty Elements

XML distinguishes between empty elements with different syntax:

<tag/>
<tag></tag>

Both are semantically equivalent in XML, but you need to decide how to represent them in JSON:

• As null: {"tag": null}
• As empty string: {"tag": ""}
• As empty object: {"tag": {}}
• Omit entirely: {}

The choice depends on your use case. For data-centric XML, null often makes the most sense. For document-centric XML, empty string might be more appropriate.

Ensuring Data Types Are Accurately Represented

XML is fundamentally text-based—everything is a string until you apply schema validation or type inference. JSON, however, has native support for numbers, booleans, null, strings, objects, and arrays. Proper type conversion is crucial for creating usable JSON.

Type Inference Challenges

Consider this XML:

<product>
  <id>12345</id>
  <price>29.99</price>
  <inStock>true</inStock>
  <quantity>0</quantity>
  <description>A great product</description>
  <sku>00123</sku>
</product>

Without type information, a naive converter might produce:

{
  "product": {
    "id": "12345",
    "price": "29.99",
    "inStock": "true",
    "quantity": "0",
    "description": "A great product",
    "sku": "00123"
  }
}

Everything is a string! This forces consumers to parse and convert types themselves. A smarter converter with type inference produces:

{
  "product": {
    "id": 12345,
    "price": 29.99,
    "inStock": true,
    "quantity": 0,
    "description": "A great product",
    "sku": "00123"
  }
}

Notice that sku remains a string because the leading zero indicates it should be treated as a string identifier, not a number.

Type Inference Rules

Good type inference follows these rules:

1. Boolean Detection: Convert "true" and "false" (case-insensitive) to boolean values
2. Null Detection: Convert empty elements or explicit "null" strings to JSON null
3. Number Detection: Convert numeric strings to numbers, but preserve leading zeros as strings
4. Integer vs Float: Use integers when there's no decimal point, floats otherwise
5. Scientific Notation: Handle exponential notation (1.5e10) correctly
6. Preserve Strings: When in doubt, keep it as a string

Schema-Driven Type Conversion

When you have an XML Schema, you can use type definitions to ensure accurate conversion:

<xs:element name="product">
  <xs:complexType>
    <xs:sequence>
      <xs:element name="id" type="xs:integer"/>
      <xs:element name="price" type="xs:decimal"/>
      <xs:element name="inStock" type="xs:boolean"/>
      <xs:element name="quantity" type="xs:nonNegativeInteger"/>
      <xs: