XML to JSON Conversion - Avoiding the Pitfalls That Actually Bite You
Converting XML to JSON is deceptively complex due to structural mismatches. A direct parse often leads to data loss, type errors, and fragile pipelines. Here are the key pitfalls to watch out for — and how to handle them correctly.
Why XML and JSON Don't Map Cleanly
XML includes features that have no direct JSON equivalent: attributes, mixed-content nodes, namespaces, and implicit ordering. Without proper parser configuration, the output is inconsistent and fragile. The three core issues are:
Silent data loss (attributes get dropped)
Type ambiguity (strings vs. arrays)
Naming conflicts from namespaces
Handling XML Attributes Without Losing Data
XML attributes — things like id, role, or currency — encode real business data, yet most parsers drop them by default. The standard convention is to prefix attribute keys with the
In fast-xml-parser for Node.js, set ignoreAttributes: false and attributeNamePrefix to a prefix string like "prefix_". The default behavior silently discards attribute data, which is a common source of hard-to-debug data loss in API migrations.
The Array Problem — The Bug That Catches Everyone
XML doesn't distinguish between a single child element and a collection. This means a one-item list parses to a plain string, while a two-item list parses to an array — so your array.map() call works fine in testing and fails in production when a single-item edge case arrives.
The fix is to declare known collection tags explicitly using the isArray callback in fast-xml-parser, or to write a post-processing normalization step that enforces array types on known plural keys like products, items, users, and orders. Pick one approach and apply it consistently across your pipeline.
Type Inference — Don't Let "42" Stay a String
XML stores everything as text. Without explicit type parsing, boolean flags come through as "true" strings, numeric IDs come through as "123" strings, and your downstream code has to compensate — or silently misbehaves.
Most parsers offer a parseTagValue: true option that handles the common cases automatically. For custom logic, a simple helper that checks for "true", "false", numeric strings, and empty values covers most real-world needs. Always pair it with trimValues: true to strip whitespace from element text.
Real-World Case Studies
SOAP to REST Migration
When moving from SOAP to REST, you must navigate through soap:Envelope and soap:Body containers using optional chaining. Always declare expected collection tags as arrays during the initial parse rather than trying to fix them in post-processing.
Config File Migration (Spring / Maven XML to JSON)
Type inference is critical here. A port number stored as XML text must be cast to a JSON integer to prevent application startup failures. Validate your output against a schema before replacing production config files.
Recommended Tools
Node.js: fast-xml-parser — fine-grained control over attributes, arrays, and types
Original article: XML to JSON Conversion: Best Practices and Common Pitfalls - DevToolLab
Quick browser-based conversion: DevToolLab XML to JSON Converter — client-side processing, no data sent to a server
