Turning SOAP XML into JSON for modern integrations

Plenty of mission-critical systems still expose SOAP web services—payment gateways, logistics providers, government and banking back-ends—while the apps that consume them are JSON to the core. Rewriting those back-ends is rarely an option, so the realistic move is to convert SOAP to JSON at the edge and keep the rest of your stack blissfully unaware that XML was ever involved. This piece covers how to do that cleanly.

Step 1: strip the envelope

A SOAP response wraps your data in scaffolding: an Envelope, then a Body, then the actual payload element. Your callers do not want three layers of wrapper—they want the payload. So the first job of an adapter is to drill into the body and take the first meaningful child before converting. Paste a sample response into the XML to JSON converter and you will see the envelope structure clearly; in code, navigate to Envelope.Body and convert from there.

Step 2: decide what happens to namespaces

SOAP leans on XML namespaces to keep elements unambiguous, so responses are full of prefixes like soap: and ns2:. A JSON consumer rarely cares about any of that. The common approach is to flatten the prefix and keep only the local name, which reads far more naturally. The one thing to check first is whether two namespaces share a local element name—if they do, flattening would collide and you need to keep a distinguishing prefix or rename on the way out. Whatever you choose, document it so the next engineer is not surprised.

Step 3: map the payload with the usual rules

Once you are past the envelope and namespaces, the payload follows the same XML to JSON rules covered in how XML maps to JSON: elements become objects, attributes become @-prefixed keys, repeated tags become arrays and stringly-typed values may need coercing to real numbers and booleans. SOAP responses are often attribute-light and deeply nested, so the array rule is the one to watch—a list of one line item looks different from a list of several.

Step 4: turn faults into a JSON error shape

SOAP signals errors with a Fault element containing faultcode and faultstring. If you convert that blindly, your callers get an XML-shaped error leaking through a JSON API. Better: detect the Fault before converting the happy path and map it into a stable JSON error object—something like { "error": { "code": "...", "message": "..." } }. Now success and failure both arrive as predictable JSON. Callers handle them with one code path.

SOAP elements and how to treat them

Step 5: pin the adapter output

An adapter is a contract. Capture its JSON output shape with the JSON Schema generator and check it in CI so a change in the upstream SOAP service surfaces as a failing test rather than a silent break downstream. When the provider revises their WSDL, run a fresh sample through the converter and compare with JSON diff to see exactly what moved.

Where this fits in the series

SOAP is one of the two most common XML sources you will convert in practice. The other is feeds—see reading RSS and Atom feeds as JSON. For the broader trade-offs, start with XML vs JSON: the practical differences.

Frequently asked questions

Do I need to keep the SOAP envelope in the JSON?
Usually not. Drill into the body, take the first meaningful child and convert that so callers get the payload directly.

How should SOAP faults be handled?
Detect the Fault element first and map it into a stable JSON error object so callers treat errors like any other JSON response.

Bottom line

Converting SOAP to JSON is mostly about discipline at the boundary: strip the envelope, tame the namespaces, apply the standard mapping rules and give faults a clean JSON shape. Do that in a thin adapter and the rest of your services never need to know SOAP was in the picture.