SOAP-to-REST Conversion Mapping Engine

Overview

The conversion engine is the core component for translating API calls between REST/JSON and SOAP/XML. Since version 1.0, it provides bidirectional conversion on a single runtime, enabling two primary use cases:

• Publish: Exposes a SOAP backend as a modern REST/JSON API. The platform converts inbound REST/JSON requests to SOAP requests and outbound SOAP responses to REST/JSON responses. The published contract is an OpenAPI v3 specification.
• Consume: Allows a SOAP-based system to call a REST API. The platform converts inbound SOAP requests to REST requests and outbound REST responses to SOAP responses. The published contract is a WSDL.

The engine's defining characteristic is its deterministic, full-field mapping. When a WSDL is imported, the platform automatically generates a complete mapping for every element in the request and response schema (XSD). This avoids manual, error-prone mapping processes and ensures that the entire data structure is converted according to the contract. There is no mediation language to author or per-service code to maintain.

This document explains the mapping model. For tunable conversion behaviors, see the conversion options reference.

How It Works

The mapping process begins when an API publisher imports a WSDL. The platform's parser analyzes 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, stamped with a checksum and the parser version used to create it.

From this canonical contract, the platform generates an explicit, compiled mapping plan. This plan is not re-calculated on each request; instead, it is cached for each active operation version, ensuring low conversion overhead.

The mapping is:

• Deterministic: A given WSDL contract will always produce the exact same mapping, and a given input payload will always produce the exact same output.
• Full-field: The generated rules traverse the entire XML tree, including wrappers, nested complex types, arrays, choices, attributes, and mixed content. It is not a simple top-level field mapping.

The diagram below illustrates the data flow for the "Publish" direction, where a SOAP service is exposed as a REST API.

flowchart TD
    subgraph API Consumer
        A[Client Application]
    end

    subgraph API Platform
        B(REST/JSON Facade)
        C(Conversion Engine: REST → SOAP)
        D(Conversion Engine: SOAP → REST)
    end

    subgraph Backend System
        E[SOAP Backend Service]
    end

    A -- 1. REST/JSON Request --> B
    B -- 2. Internal Call --> C
    C -- 3. SOAP Request --> E
    E -- 4. SOAP Response --> D
    D -- 5. Internal Call --> B
    B -- 6. REST/JSON Response --> A

Request Mapping (REST → SOAP)

In the Publish direction, the engine receives an inbound REST/JSON request and constructs a valid SOAP/XML envelope to send to the backend service. This involves several steps:

1. Contract-Root Resolution: The engine identifies the operation's input message part and resolves its corresponding element and full XSD tree. It supports document/literal (wrapped and bare) and rpc/literal message styles.
2. Wrapper Synthesis: The engine automatically inserts any SOAP wrapper elements required by the schema. For example, it wraps individual items in a list with their declared item element name, ensuring the backend receives a valid, schema-compliant envelope.
3. Cardinality and Requiredness: The mapping enforces minOccurs and maxOccurs constraints from the XSD. If a required field is missing from the JSON request, the engine rejects the call with a validation error before it reaches the backend.
4. Type Coercion and Formatting: JSON values are coerced into their schema-defined XML types, including booleans, numerics (with range and precision checks), dates/times, and binary data. This behavior can be tuned via conversion options.
5. Namespace and Prefix Policy: The engine emits the correct namespace URI for each XML element and allocates stable prefixes, preserving the semantic integrity of the payload.
6. Nullability: A JSON null value for an element defined as nillable="true" in the XSD is converted to an XML element with an xsi:nil="true" attribute. A null value for a non-nillable element results in a validation error.
7. Sequence and Choice Enforcement: The order of elements in an xsd:sequence is preserved. For an xsd:choice, the engine enforces that exactly one of the possible branches is present.

In the Consume direction, this process runs in reverse: an inbound SOAP request is parsed and validated against the schema to build the outbound REST request.

Response Mapping (SOAP → REST)

For the SOAP response from the backend, the engine produces a stable, typed JSON response for the API consumer.

1. Envelope and Wrapper Unwrapping: The engine strips the soap:Envelope, soap:Body, and <OperationNameResponse> wrapper elements to expose the core payload. The exact elements to remove are determined by a recorded unwrapChain.
2. Wrapper-Aware Collection Parsing: The engine correctly identifies wrapped and unwrapped collections in the SOAP payload and converts them into JSON arrays. It preserves the distinction between a null list and an empty list.
3. Type Coercion: Text-based values in the SOAP/XML payload are converted to their corresponding JSON types (number, boolean, string) based on the XSD schema. Dates and times are formatted as ISO strings.
4. Null and Empty Value Handling:
   • An element with xsi:nil="true" becomes a JSON null.
   • An empty element is handled according to the configured policy for its type.
   • A missing optional element is omitted from the JSON object by default.

Fault Normalization

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

The shape of the resulting JSON error object is determined by the error-shape conversion option, which supports:

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

The HTTP status code returned to the API consumer is governed by the upstream-failure-status option, which can either propagate the backend's status or mask it (e.g., as 200 OK).

WSDL-defined faults (wsdl:fault) and their detail contracts are reflected in the generated OpenAPI v3 specification, allowing API consumers to anticipate the shape of potential error responses.

Generated Rule Artifacts

The generated mapping is not a black box; it is an explicit and inspectable set of artifacts.

• Request Mapping: Records the root operation, input element, 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, and namespace.
• Response Mapping: Records the response root element, the unwrapChain[], and a rules[] list of instructions. Each rule defines a mapping from a fromSoapPath to a toJsonPath with its type, coercion rules, and null/array policies.
• Fault Mapping: Contains the fault translation table and an optional rule for extracting business errors from non-fault (i.e., HTTP 200) responses.

Every artifact is stamped with the mapping-engine version, contract version, contract parser version, and contract checksum, providing full traceability from a live mapping back to the exact contract it was generated from.

Versioning and Immutability

Mappings are immutable and versioned. When a service version is activated, the platform makes its compiled mapping plan live. Any subsequent edits, such as applying a field-level override, create a new, distinct revision rather than mutating the active one. This model ensures stability and allows an API publisher to roll back to any previously active version at any time.

See Also

• Conversion Options Reference
• SOAP & XSD Support
• Field-Level Overrides
• Validation Modes
• Publish & Version a Service
• Import a WSDL
• Consume Direction

All SOAP-to-REST docs