Converting XML to JSON

The XML Information Set (Second Edition) section 2 defines eleven kinds of information item: document, element, attribute, processing instruction, unexpanded entity reference, character, comment, document type declaration, unparsed entity, notation and namespace. JSON, per RFC 8259, has objects, arrays, strings, numbers, booleans and null. Nothing else.

Five properties of an XML document have no JSON counterpart at all, and each one forces a decision:

• Order. XML children are an ordered sequence. RFC 8259 section 1 defines a JSON object as "an unordered collection of zero or more name/value pairs", so sibling order is not representable.
• Attributes. XML has two ways to attach a scalar to an element. JSON has one, so the two must either be merged (and risk colliding) or distinguished by a naming convention.
• Cardinality. XML has no way to say "this element may repeat" without a schema. JSON distinguishes a value from a one-element array structurally.
• Mixed content. Text interleaved with elements is ordinary in XML and impossible in a JSON object.
• Namespaces. A name in XML is a URI plus a local part. A JSON key is a string.

Michael Kay put the general problem well in "Schema-Aware Conversion of XML to JSON" (Balisage volume 28): a generic converter "is guessing what the semantics of the object model are that lie behind the lexical XML, and it's guessing wrong", because the object model cannot in general be reverse-engineered from the XML representation. A converter that offers no options is not simpler: it has made the same guesses, silently.

These two are worth taking together because they are the ones that reach production. The attribute question is the easier of the two. Consider two documents most people would call equivalent:

<user id="7"/>
<user><id>7</id></user>

Merging them onto one key gives the intuitive `{"user":{"id":"7"}}` for both, which is what Parker, GData and xml2js with `mergeAttrs: true` produce. The cost appears when a document has both, as `<user id="7"><id>8</id></user>` does. One key, two values, and RFC 8259 section 4 warns that when names within an object are not unique "the behavior of software that receives such an object is unpredictable". Prefixing attributes, the `@_` of fast-xml-parser or the `@` of BadgerFish, removes the collision at the cost of a key that is not a valid identifier in most languages.

The cardinality problem is worse, because nothing fails at conversion time. XML carries no occurrence information; `minOccurs` and `maxOccurs` live in the schema, not the instance. So a converter looking only at the document has to infer cardinality by counting, and a list that happens to hold one item on this request looks exactly like a scalar.

<items><item>a</item></items>
  ->  { "items": { "item": "a" } }

<items><item>a</item><item>b</item></items>
  ->  { "items": { "item": ["a", "b"] } }

// items.item.map(f) throws on the first response:
// TypeError: items.item.map is not a function

// alwaysArray: ['item']

<items><item>a</item></items>
  ->  { "items": { "item": ["a"] } }

<items><item>a</item><item>b</item></items>
  ->  { "items": { "item": ["a", "b"] } }

fast-xml-parser concedes the point in its own documentation: "Whether a single tag should be parsed as an array or an object, it can't be decided by FXP." Its answer is the `isArray(tagName, jPath, isLeafNode, isAttribute)` callback, which asks you. xml2js takes the opposite route and defaults `explicitArray: true`, wrapping every child in an array whether it repeats or not. That is consistent and ugly: `result.user[0].name[0]` for a document with exactly one of each.

Mixed content is the case with no good answer. An element with text and element children has ordered children of two different kinds, and a JSON object cannot hold that order.

<root>35<nested>34</nested>46</root>

{ "root": { "nested": "34", "#text": "3546" } }

Note that "35" and "46" have fused into "3546". fast-xml-parser does exactly the same thing. Goessner's original 2006 convention gave up differently and degraded mixed content to a string of raw markup, treating it as unknown. BadgerFish's author lists the gap as a known defect: it "doesn't provide a way to get the different text bits in an element whose content is a mix of text and children". Only JsonML gets this right, because it uses arrays, which are ordered.

Whitespace-only text nodes are the same problem in miniature. Pretty-printing puts a newline and an indent between every element, and those are character information items like any other. XML 1.0 (Fifth Edition) section 2.10 lets an author declare intent with `xml:space="preserve"`, but almost nobody does, so converters guess. Trimming is the near-universal default: right for data documents, wrong for poetry, code listings and anything where the layout is the content.

Comments and processing instructions have no JSON representation at all. Most converters drop both; this one will put comments under a `#comment` key if you ask, and discards processing instructions unconditionally, which matters if your document carries an `<?xml-stylesheet?>` something downstream depends on.

Empty elements have four plausible mappings and no principled way to choose: `null` (Goessner), `""` (xml2js `emptyTag`), `{}`, or `{"#text": ""}`. The one hard rule is that `<e/>` and `<e></e>` are the same infoset, so a converter that distinguishes them has a bug. This site emits the empty string, because `null` invites a null check the XML never justified.

A prefix is not part of an element's name. The name is the namespace URI plus the local part, and the prefix is a document-local abbreviation an author may change without changing the meaning. JSON has neither, so every converter picks a lossy encoding: keep the prefixed name (`soap:Body`), strip it (`Body`), carry the namespace scope in a sidecar (BadgerFish's `@xmlns`, repeated on every element where it is in scope), or mangle the colon (GData turns `openSearch:startIndex` into `openSearch$startIndex`).

Keeping the prefix is honest and awkward, because `obj["soap:Body"]` is the only way to reach the key in JavaScript. Stripping it is pleasant right up to the moment two namespaces collide, and then it is silent data loss:

<record xmlns:dc="http://purl.org/dc/elements/1.1/"
        xmlns:cust="urn:acme:fields">
  <dc:title>Report</dc:title>
  <cust:title>Q3 internal</cust:title>
</record>

// removeNamespacePrefix: false
{ "record": {
    "@_xmlns:dc": "http://purl.org/dc/elements/1.1/",
    "@_xmlns:cust": "urn:acme:fields",
    "dc:title": "Report",
    "cust:title": "Q3 internal" } }

// removeNamespacePrefix: true
{ "record": {
    "@_dc": "http://purl.org/dc/elements/1.1/",
    "@_cust": "urn:acme:fields",
    "title": ["Report", "Q3 internal"] } }

Two elements from different vocabularies have become an array of two strings, indistinguishable from a genuinely repeated element. There is a second-order effect too: `xmlns:dc` is an attribute like any other, so stripping prefixes rewrites the declaration into a key called `dc`. Strip prefixes when you control the vocabulary and know it is single-namespace. Never on a SOAP envelope.

XML without a schema is text. Every value is a string, and a converter that turns "123" into the number 123 is guessing at a type the document never claimed. Usually the guess is convenient and right. The failures are not rare edge cases: they are identifiers.

Booleans have a quieter version of the same problem. `<active>true</active>` should almost certainly be a boolean. `<answer>true</answer>` in a quiz application should almost certainly be a string. The document does not distinguish them and neither can the converter.

Coercion is off by default here, and the `coerce` function is conservative even when it is on. It accepts only values matching `^-?(0|[1-9][0-9]*)(\.[0-9]+)?([eE][-+]?[0-9]+)?$`, which excludes leading zeros by construction, then applies a round-trip test: the string becomes a number only if `String(n)` is byte-identical to the input. That one check rejects "1.20", "1.0" and every integer too long for a double.

Six conventions have names. Using `<alice charlie="david">bob</alice>` as the common input, here is what each produces:

// Goessner / fast-xml-parser (attributeNamePrefix: "@_")
{ "alice": { "@_charlie": "david", "#text": "bob" } }

// xml2js defaults (attrkey "$", charkey "_", explicitArray true)
{ "alice": { "$": { "charlie": "david" }, "_": "bob" } }

// BadgerFish
{ "alice": { "$": "bob", "@charlie": "david" } }

// Parker (attributes discarded, root absorbed)
"bob"

// GData
{ "alice": { "$t": "bob", "charlie": "david" } }

// JsonML
["alice", { "charlie": "david" }, "bob"]

The XML to JSON tool defaults to the Goessner shape with `@_` for attributes and `#text` for text, arrays only where an element genuinely repeats, whitespace trimmed, prefixes kept, comments dropped, and type coercion off. The reasoning: it is the convention engineers already recognise from fast-xml-parser, xml2js and the AWS SDK, the output is readable enough to paste into a bug report, and it is the only widely used convention that keeps attributes without wrapping every scalar in an object.

Two defaults are chosen against the crowd, and both are about not lying to you:

• Coercion is off. A converter that silently turns 01730 into 1730 is worse than useless for exactly the values people most often convert. You can turn it on, and the result panel says what it did.
• A text-only element with no attributes collapses to a plain string, so `<name>Alice</name>` becomes "Alice" rather than `{ "#text": "Alice" }`. Entity references are resolved, so `A &amp; B` becomes "A & B" in both text and attribute values.

The tool reports every decision it made: the namespaces it found and the risk of stripping them, the fact that values were kept as strings, and a prompt to declare the repeating elements when arrays were auto-detected. Hiding those decisions is how a converter becomes a source of bugs several services downstream.

Going the other way, the JSON to XML tool has the mirror problem: XML 1.0 section 2.3 restricts element names to the `Name` production, so JSON keys like "2024", "first name" and "user@email" are illegal. It sanitises rather than escaping, keeps distinct keys distinct, and lists every rename in the output panel.