Turning SOAP XML into JSON for modern integrations
How to convert SOAP XML responses into clean JSON: strip the envelope, flatten namespaces, handle faults and build a thin adapter modern services consume.
Quick Answer
Converting SOAP to JSON means stripping the SOAP envelope and body wrappers, flattening namespace prefixes you do not need, mapping the payload with the usual XML to JSON rules and translating SOAP faults into a JSON error shape your callers understand. A thin adapter at the boundary keeps the rest of your stack JSON-only.
Search Snapshot
- Format
- Engineering
- Reading time
- 5 min
- Last updated
- June 12, 2026
- Primary topic
- SOAP to JSON
- Intent
- informational
Key Takeaways
Point 1
Strip the Envelope and Body wrappers so callers see the payload, not the SOAP scaffolding.
Point 2
Decide how namespace prefixes should appear before they collide on a shared local name.
Point 3
Translate SOAP faults into a consistent JSON error object instead of leaking XML.
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
| SOAP element | Treatment in JSON |
|---|---|
| Envelope | Drop—transport scaffolding |
| Body | Drop—drill in to the payload child |
| Payload element | Convert with the standard XML to JSON rules |
| Namespace prefix (soap:, ns2:) | Flatten unless two namespaces collide on a local name |
| Fault / faultcode / faultstring | Map to a stable JSON error object |
What to do with each part of a SOAP response when converting to JSON.
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.
Get new playbooks weekly
Actionable guides, market updates and shipping notes — once a week.