Introduction
If you've worked on a system old enough to have "legacy" in its name, there's a good chance XML is involved somewhere. SOAP APIs, enterprise config files, old EDI pipelines, ancient Java frameworks that predate JSON's popularity — XML is still everywhere in backend systems, even as nearly everything new defaults to JSON. At some point, most teams end up needing to migrate data between the two, and it's rarely as clean as it looks on paper.
This post walks through why that migration is harder than it seems, the mistakes that show up most often, and a more reliable approach for doing it without losing data or introducing subtle bugs.
The Problem
On the surface, JSON and XML both represent structured, hierarchical data, so converting between them feels like it should be mechanical — swap tags for keys, done. In practice, XML supports several concepts that JSON has no native equivalent for: attributes vs. child elements, mixed content (text and elements interleaved), namespaces, and document ordering that sometimes carries semantic meaning. JSON has none of that. It only has objects, arrays, strings, numbers, booleans, and null.
That mismatch means a naive converter has to make judgment calls, and different tools make them differently. One converter turns every XML attribute into a JSON key prefixed with @. Another drops attributes into a _attributes sub-object. A third just merges them into the parent object and silently overwrites a child element that happens to have the same name. None of these are "wrong" exactly, but if your downstream code expects one convention and gets another, you get a bug that looks like a parsing issue but is actually a modeling disagreement.
Why It Happens
Most of these migrations start as "just write a script." Someone grabs an XML parsing library, walks the tree, and builds a JSON object as they go. It works on the sample file they tested with. It ships. Then, three months later, someone hits a document with a repeated element that should become an array but instead overwrites itself, or a namespace prefix that breaks a downstream if statement checking key names, or a numeric-looking string that XML explicitly typed as text but JSON happily coerces to a number.
The underlying issue is that ad hoc converters are usually built against a handful of example documents rather than the actual schema, so they only handle the shapes the author happened to think of.
Common Mistakes
A few patterns account for most of the pain:
Losing attribute vs. element distinction. If Alice and 42Alice both become {"user": {"id": 42, "text": "Alice"}}, you can no longer round-trip back to the original XML shape, which matters if the other system still expects it.
Silently collapsing repeated elements. A single becomes a JSON string or object; two or more elements should become an array — but only if the converter is consistent about it regardless of count. Inconsistent handling here is one of the most common sources of "works on this file, breaks on that one" bugs.
Ignoring namespaces. Dropping namespace prefixes might look like a cleanup, but if two elements from different namespaces share a local name, you've just merged two unrelated fields.
Type coercion surprises. XML has no types — everything is text until you say otherwise. JSON converters often guess: a leading zero on a string like "0042" might turn into 42, quietly corrupting IDs or zip codes.
No round-trip testing. Converting XML → JSON → XML and diffing the result against the original is the cheapest way to catch all of the above, and it's skipped more often than not.
A Better Approach
The fix isn't to write a smarter one-off script — it's to stop treating this as a one-off. A few practical habits:
Decide your attribute convention up front (prefix, sub-object, or merge) and apply it consistently, then document it so the next person doesn't reinvent it.
Force arrays for elements that can repeat, even when a given document only has one instance, so your downstream code doesn't have to special-case "is this a string or a list."
Preserve types explicitly where XML schema (or just convention) implies them, rather than letting a generic parser guess.
Round-trip test a representative sample of real documents, not just your happy-path example.
Use a conversion layer you don't have to maintain yourself for anything beyond a trivial, stable schema. It's rarely a good use of engineering time to hand-roll and maintain an XML/JSON converter for years.
How ZenithConvert Helps
This is the exact class of problem ZenithConvert is built for — an AI-powered format converter that handles JSON, XML, YAML, CSV, and close to 100 format pairs total, including the edge cases above (attributes, repeated elements, type ambiguity) instead of leaving you to special-case them. For one-off conversions there's a free online converter; for pipelines and CI, the REST API (with JS and Python SDKs) lets you drop conversion into a build step instead of maintaining a bespoke script. Guest use is capped at 3 conversions/day, a free account gets 5/day, and the API is available on paid plans for teams doing this at volume.
Conclusion
JSON-to-XML (and back) migrations look like a formatting exercise until you hit the handful of structural differences that don't map cleanly — attributes, repeated elements, namespaces, and types. Most of the bugs teams hit in production trace back to a converter that made an implicit, inconsistent choice about one of these. Deciding those conventions deliberately, testing round-trips, and offloading the actual conversion logic to a tool built for it will save more debugging time than it costs to set up.
CTA: If you're maintaining a homegrown XML/JSON converter and want to see how it handles your actual documents, give ZenithConvert a spin — free tier included.
Top comments (0)