Data Formats
XML Arrays Explained: Repeated Elements, Lists, and JSON Mapping
XML has no built-in array literal. List-shaped data is normally represented by repeated elements, often inside a container element, and the converter must decide when those siblings become a JSON array.
Published
Repeated elements represent list items
The two order siblings form a natural list. Their order remains visible in the XML document and maps naturally to an ordered JSON array.
<orders>
<order id="1"><total>12.50</total></order>
<order id="2"><total>8.00</total></order>
</orders>Map repeated siblings to a JSON array
The array preserves each repeated order as a separate value. Attribute and scalar-type policies are independent mapping decisions.
{
"orders": {
"order": [
{ "@attributes": { "id": "1" }, "total": "12.50" },
{ "@attributes": { "id": "2" }, "total": "8.00" }
]
}
}The single-item ambiguity
A converter that infers arrays only from repetition may produce an object for the first document and an array for the second. Force known item names such as order to arrays when consumers require a stable schema.
One document: <orders><order id="1"/></orders>
Another: <orders><order id="1"/><order id="2"/></orders>Container elements and direct repetition
| Pattern | Example | Trade-off |
|---|---|---|
| Container + items | <tags><tag>a</tag></tags> | Clear list boundary and room for list metadata |
| Direct repetition | <tag>a</tag><tag>b</tag> | Compact inside an already defined parent |
| Delimited text | <tags>a,b</tags> | Not structural; escaping and empty values become application-specific |
Common XML array mapping pitfalls
- Changing the JSON type between object and array when the item count changes.
- Losing attributes attached to individual repeated elements.
- Splitting comma-delimited text without an explicit vocabulary rule.
- Flattening nested lists before confirming what the consumer expects.
Try the example
Map repeated order elements to an array
Two siblings with the same name form a natural JSON array.
<orders><order id="1"><total>12.50</total></order><order id="2"><total>8.00</total></order></orders>Expected result: The order key contains an array with two objects in document order.
Test the array policy
Convert repeated XML elements to JSON
Load a list, compare automatic and forced-array behavior, and inspect the exact output structure.