SOAP-to-REST Conversion Engine Mapping Model

Overview

The conversion engine is the core component responsible for translating API calls between REST/JSON and SOAP formats. It enables API publishers to expose a modern REST/JSON interface for a backend SOAP service, or to consume a REST service from a SOAP-based client, without writing or maintaining per-service mediation code.

The engine operates bi-directionally on a single runtime:

• Publish Direction: Converts an inbound REST/JSON request into a SOAP request for a backend service, and converts the resulting SOAP response back into a REST/JSON response for the API consumer. The published contract is an OpenAPI v3 specification.
• Consume Direction: Converts an inbound SOAP request into a REST request for a backend service, and converts the resulting REST response back into a SOAP response for the API consumer. The published contract is a WSDL.

The engine's mapping model is deterministic and full-field. This means that for a given WSDL/XSD contract, the conversion rules are generated automatically to cover every element in the schema, and the output is always the same for a given input. The mapping is a compiled, cached plan, ensuring low-latency conversions.

How it works

The conversion process begins when an API publisher imports a WSDL. The platform parses the WSDL and its associated XSDs to create a canonical contract for each operation. This contract is an immutable, versioned snapshot of the full request and response schema trees. From this contract, the engine generates an explicit set of mapping rules.

"Deterministic" means the same contract always produces the same mapping. "Full-field" means the generated rules traverse the entire schema tree, including wrappers, nested complex types, arrays, choices, attributes, and mixed content.

The following diagram illustrates the data flow for the "Publish" direction, where a REST API call is converted to a backend SOAP call.

sequenceDiagram
    participant C as API Consumer
    participant P as API Platform
    participant B as SOAP Backend

    C->>P: 1. REST/JSON Request
    P->>P: 2. Convert to SOAP using<br/>compiled mapping plan
    P->>B: 3. SOAP Request
    B-->>P: 4. SOAP Response / Fault
    P->>P: 5. Convert to REST/JSON using<br/>compiled mapping plan
    P-->>C: 6. REST/JSON Response / Error

Request Mapping (REST → SOAP)

For an inbound REST/JSON request in the Publish direction, the engine constructs a valid SOAP envelope by performing the following steps:

1. Contract-Root Resolution: Resolves the operation's input message part to its corresponding element or type and the full XSD tree. The engine supports document/literal (wrapped and bare) and rpc/literal styles.
2. Wrapper Synthesis: Automatically inserts required SOAP wrapper elements based on the schema. For example, it wraps individual list items in their declared parent element to ensure the backend receives a valid, structured envelope.
3. Cardinality and Requiredness: Enforces minOccurs and maxOccurs constraints from the schema. If a required field is missing from the request, the engine rejects the call with a validation error before it reaches the backend.
4. Type Coercion and Formatting: Coerces JSON values (booleans, numbers, strings) into their schema-defined XML types, including dates, times, and binary data. This process includes range and precision checks for numeric types and respects configured conversion options.
5. Namespace and Prefix Policy: Emits the correct XML namespace for each node and allocates stable prefixes, preserving the semantic namespace URI.
6. Nullability: Translates JSON null values according to the schema. A null for an element defined as nillable="true" becomes an element with an xsi:nil="true" attribute. A null for a non-nillable element results in a validation error.
7. Sequence Order: Preserves the element order defined by xsd:sequence and enforces that exactly one branch of an xsd:choice is present.

Response Mapping (SOAP → REST)

When receiving a SOAP response from the backend, the engine produces a stable, typed JSON object for the API consumer:

1. Envelope and Wrapper Unwrapping: Strips the Envelope/Body/<OperationResponse> wrappers to expose the core payload, following the unwrapChain recorded in the mapping artifact.
2. Wrapper-Aware Collection Parsing: Deterministically converts SOAP structures, including object and primitive wrappers, into JSON arrays. The engine preserves the distinction between an empty list and a null list.
3. Type Coercion by Schema: Converts SOAP text values into typed JSON values (number, boolean, ISO-formatted date/time, etc.) based on the XSD and configured conversion options.
4. Null and Empty Node Handling:
   • An element with xsi:nil="true" becomes a JSON null.
   • An empty element is handled according to the configured null/empty policy for its type.
   • A missing optional element is omitted from the JSON output by default.

Fault Normalization

The engine normalizes SOAP Faults into a deterministic REST error shape. It handles both SOAP 1.1 (faultcode, faultstring, detail) and SOAP 1.2 (Code/Value, Subcode) faults.

The final shape of the error response is determined by the error-shape conversion option, which supports:

• A platform-default error object
• RFC 7807 Problem Details
• A flat error body
• Passing the upstream fault detail through unchanged

The HTTP status code returned to the consumer is controlled by the upstream-failure-status option. WSDL-declared faults (wsdl:fault) and their detail contracts are reflected in the generated OpenAPI v3 specification, allowing API consumers to anticipate error structures.

Generated Mapping Artifacts

The generated mapping is an explicit, inspectable artifact, not a black box. Each artifact contains metadata that links it to its exact origin, including the mapping-engine version, contract version, contract parser version, and contract checksum.

• Request Mapping: Records the root operation and input element, the wrapper policy, and a rules[] list of compiled instructions. Each rule defines a mapping from a fromJsonPath to a toSoapPath with its associated type, coercion rules, requiredness, and namespace.
• Response Mapping: Records the response root element, the unwrapChain[] used to locate the payload, and a rules[] list. Each rule defines a mapping from a fromSoapPath to a toJsonPath with its type, coercion rules, and null/array handling policies.
• Fault Mapping: Contains the fault translation table and an optional rule for extracting business errors from nodes within an otherwise successful (200 OK) response.

Versioning and Immutability

Since v1.0, mappings are immutable and versioned. When a service version is activated, the platform uses a snapshot of its mapping. Any change, such as a field-level override, creates a new, distinct revision rather than modifying the active one. This design allows API publishers to roll back to any previously active version at any time.

Configuration Reference

The behavior of the conversion engine can be tuned with various options. The source for this document mentions the following options. For a complete reference, see Conversion options reference.

Troubleshooting

The engine can produce errors at two main stages: during request validation or upon receiving a fault from the backend.

Request Validation Errors

These errors occur before the request is sent to the backend SOAP service. They are triggered by an inbound REST request that violates the WSDL/XSD contract.

• Missing Required Field: The request is missing a field that the schema defines with minOccurs="1" (or a higher value).
• Invalid Cardinality: The request provides too many items for a field constrained by maxOccurs.
• Non-Nillable Null: The request provides a null value for a field that is not nillable="true" in the schema.
• Invalid xsd:choice: The request provides more than one of the possible elements within an xsd:choice structure.

Backend Faults

If the backend service returns a <soap:Fault>, the engine normalizes it into a REST error response as described in the Fault Normalization section. The structure and status code of the final error are determined by the error-shape and upstream-failure-status conversion options.

See Also

• Conversion options reference
• SOAP & XSD support
• Field-level overrides
• Validation modes
• Import a WSDL
• Publish & version a service
• Consume direction

All SOAP-to-REST docs