Convert OpenAPI JSON to XML for SOAP Integration

OpenAPI (formerly Swagger) defines REST APIs in JSON or YAML. SOAP services define their interface in WSDL — an XML vocabulary. When you need to expose a REST API to an enterprise system that only speaks SOAP, or when legacy middleware in your integration layer requires XML payloads, you need to bridge these two worlds.

The most common scenarios are: an enterprise ESB (Enterprise Service Bus) like MuleSoft, IBM App Connect, or Apache Camel that routes messages via SOAP; a banking or insurance partner whose systems predate REST; or a government integration endpoint that mandates SOAP with WS-Security. Understanding what SOAP actually needs from the XML helps you generate the right output.

An OpenAPI 3.0 document describes paths (routes), operations (HTTP methods), parameters, request bodies, and responses. The schemas section defines the data structures. This is the information you need to extract when generating WSDL or XML payloads.

{
  "openapi": "3.0.3",
  "info": { "title": "User Service", "version": "1.0.0" },
  "paths": {
    "/users/{id}": {
      "get": {
        "operationId": "getUser",
        "parameters": [
          { "name": "id", "in": "path", "required": true,
            "schema": { "type": "integer" } }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/User" }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "User": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "name": { "type": "string" },
          "email": { "type": "string", "format": "email" }
        },
        "required": ["id", "name"]
      }
    }
  }
}

A direct structural conversion of JSON to XML — what Just Formatter's JSON to XML tool produces — gives you a starting point. Each JSON object becomes an XML element, each string/number value becomes element text content, and arrays become repeated elements:

<?xml version="1.0" encoding="UTF-8"?>
<root>
  <openapi>3.0.3</openapi>
  <info>
    <title>User Service</title>
    <version>1.0.0</version>
  </info>
  <components>
    <schemas>
      <User>
        <type>object</type>
        <properties>
          <id><type>integer</type></id>
          <name><type>string</type></name>
          <email><type>string</type><format>email</format></email>
        </properties>
      </User>
    </schemas>
  </components>
</root>

This generic XML representation is useful for: importing into XML-based documentation systems, sending the spec structure to XML-native tooling, or as a base for manually crafting the WSDL. For full SOAP integration, you need to go further and generate a proper WSDL file.

SOAP (Simple Object Access Protocol) messages are XML documents. A SOAP request wraps your payload in an Envelope element with optional Header and mandatory Body sections. WSDL (Web Services Description Language) is the XML file that describes the SOAP service — analogous to an OpenAPI document, but in XML.

A WSDL defines: types (XML Schema for request/response objects), messages (what parameters each operation sends and receives), portType (the interface definition), binding (how the portType maps to SOAP), and service (the endpoint URL). Generating a correct WSDL from an OpenAPI spec requires mapping each concept.

For the User Service example, here is a WSDL that exposes the getUser operation as a SOAP service:

<?xml version="1.0" encoding="UTF-8"?>
<definitions xmlns="http://schemas.xmlsoap.org/wsdl/"
             xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
             xmlns:tns="http://userservice.example.com/"
             xmlns:xsd="http://www.w3.org/2001/XMLSchema"
             name="UserService"
             targetNamespace="http://userservice.example.com/">

  <types>
    <xsd:schema targetNamespace="http://userservice.example.com/">
      <xsd:element name="getUserRequest">
        <xsd:complexType>
          <xsd:sequence>
            <xsd:element name="id" type="xsd:integer"/>
          </xsd:sequence>
        </xsd:complexType>
      </xsd:element>
      <xsd:element name="getUserResponse">
        <xsd:complexType>
          <xsd:sequence>
            <xsd:element name="id" type="xsd:integer"/>
            <xsd:element name="name" type="xsd:string"/>
            <xsd:element name="email" type="xsd:string" minOccurs="0"/>
          </xsd:sequence>
        </xsd:complexType>
      </xsd:element>
    </xsd:schema>
  </types>

  <message name="GetUserInput">
    <part name="parameters" element="tns:getUserRequest"/>
  </message>
  <message name="GetUserOutput">
    <part name="parameters" element="tns:getUserResponse"/>
  </message>

  <portType name="UserServicePortType">
    <operation name="getUser">
      <input message="tns:GetUserInput"/>
      <output message="tns:GetUserOutput"/>
    </operation>
  </portType>

  <binding name="UserServiceBinding" type="tns:UserServicePortType">
    <soap:binding style="document"
                  transport="http://schemas.xmlsoap.org/soap/http"/>
    <operation name="getUser">
      <soap:operation soapAction="getUser"/>
      <input><soap:body use="literal"/></input>
      <output><soap:body use="literal"/></output>
    </operation>
  </binding>

  <service name="UserService">
    <port name="UserServicePort" binding="tns:UserServiceBinding">
      <soap:address location="https://api.example.com/soap"/>
    </port>
  </service>
</definitions>

OpenAPI uses JSON Schema types. WSDL uses XML Schema (XSD) types. The mapping between them is straightforward for primitives but requires care for optional fields and arrays:

• OpenAPI integer → XSD xsd:integer or xsd:int
• OpenAPI number → XSD xsd:decimal or xsd:double
• OpenAPI string → XSD xsd:string
• OpenAPI boolean → XSD xsd:boolean
• OpenAPI string with format: date → XSD xsd:date
• OpenAPI string with format: date-time → XSD xsd:dateTime
• OpenAPI array of T → XSD xsd:sequence with maxOccurs='unbounded'
• OpenAPI optional property → XSD element with minOccurs='0'
• OpenAPI required property → XSD element with minOccurs='1' (default)

For large OpenAPI specs with many operations, manual WSDL writing is impractical. Several tools automate the conversion:

• openapi2soap (npm) — converts OpenAPI 3.0 to WSDL 1.1 automatically
• API Transformer (apimatic.io) — cloud-based converter supporting OpenAPI → WSDL
• SoapUI — import an OpenAPI spec and generate a mock SOAP service with WSDL export
• MuleSoft Anypoint Studio — design center converts REST specs to SOAP/RAML for Mule ESB integration
• IBM API Connect — generates SOAP adapters from REST APIs for enterprise integration

For quick structural inspection of an OpenAPI JSON spec before starting the WSDL work, Just Formatter's JSON to XML converter converts the spec to XML instantly. This lets you see the structure in XML syntax — useful when you are reading the spec and designing the WSDL types section in parallel.

Once the WSDL is generated and your SOAP endpoint is running, test it with a raw SOAP request before connecting enterprise middleware:

# Send a SOAP request with curl
curl -X POST https://api.example.com/soap \
  -H "Content-Type: text/xml; charset=utf-8" \
  -H "SOAPAction: getUser" \
  -d '<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
               xmlns:tns="http://userservice.example.com/">
  <soap:Body>
    <tns:getUserRequest>
      <tns:id>1</tns:id>
    </tns:getUserRequest>
  </soap:Body>
</soap:Envelope>'

If the response is an XML SOAP Fault, parse the faultcode and faultstring elements — they contain the specific error from your service. SOAPAction header is required by most SOAP 1.1 implementations; omitting it causes a 500 or 400 error even when the XML body is correct.