Round Trip and Limitations

Round-Trip and Limitations

This is the most important thing to understand before using the library in production: converting XML → JSON is not a perfect inverse of JSON → XML. Some inherent ambiguities of the XML format make a bit-for-bit reconstruction impossible, and ignoring them can lead to "silent" bugs.

Single element vs. list

An element that appears only once becomes a single object, not a one-element array. If your schema expects a certain tag to always be a list (even with a single item), use forceArrayTags:

$converter = new XmlToJsonConverter(forceArrayTags: ['Note']);

This way, <Notes><Note>...</Note></Notes> always produces {"Notes": {"Note": [ {...} ]}}, preventing the JSON shape from changing (from object to array) the day that tag starts repeating.

CDATA vs. plain text

<x>a</x> and <x><![CDATA[a]]></x> produce the same JSON value "a" — the information "this was in CDATA" is not recoverable.

Empty element

<note/> becomes null. If it only has attributes (e.g. <areaCode codeArea="XXX"/>), it becomes {"@codeArea": "XXX"}, with no #text key.

Other cases to keep in mind

• Comments and processing instructions are ignored when reading.
• A root-level JSON array of plain scalars is repeated as <item>...</item>, but converting back to JSON turns it into an object with an item key → list, no longer a "bare" array.
• A JSON object with non-sequential numeric keys (e.g. "0", "2") is not treated as a list: it's wrapped in a single node, and children with numeric keys use itemNodeName instead of the original key name.

None of these behaviors are bugs: they're inherent consequences of the XML↔JSON ambiguity, documented here on purpose to avoid surprises.

---

⬅️ Previous page: Conventions · ➡️ Next page: Security-and-Error-Handling