Conversion Engine Mapping Model

Overview

The conversion engine is the core component for bidirectional transformation between REST/JSON and SOAP messages. It enables two primary integration patterns on a single runtime, starting from version 1.0:

• Publish: An API publisher exposes a SOAP backend as a modern REST/JSON API. The engine converts inbound REST requests to SOAP requests and outbound SOAP responses to REST/JSON responses. The published contract is an OpenAPI v3 document.
• Consume: An API publisher integrates with a REST backend from a SOAP-based system. The engine converts inbound SOAP requests to REST requests and outbound REST responses to SOAP responses. The published contract is a WSDL document.

The engine's mapping model is deterministic and full-field. This means that for a given WSDL/XSD contract, the resulting mapping is always the same, and it covers every element in the request and response structure automatically. This approach eliminates the need for manual mapping, custom mediation logic, or per-service code.

This document describes the mapping model. For configurable behaviors that modify the output, see the Conversion options reference.

How it works

The mapping process begins when an API publisher imports a WSDL file. The platform's parser analyzes the WSDL and its associated XSDs to create a canonical contract for each operation. This contract is an immutable snapshot of the complete XSD tree for both the request and response messages, stamped with a checksum and the parser version.

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 to ensure low conversion overhead.

The "deterministic" principle ensures that the same contract always generates the identical mapping. The "full-field" principle guarantees that the mapping rules traverse the entire schema tree, including wrappers, nested complex types, arrays, choices (xsd:choice), attributes, and mixed content.

The following diagram 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 Request) --> C{Conversion Engine<br/>Request Mapping};
        C --> D(SOAP Request);
        H(REST/JSON Response) --> I[A];
        G{Conversion Engine<br/>Response Mapping} --> H;
        F(SOAP Response) --> G;
    end

    subgraph "API Publisher Backend"
        E[SOAP Backend Service]
    end

    A --sends--> B;
    D --calls--> E;
    E --returns--> F;

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: It identifies the operation's input message part and resolves its corresponding element or type from the canonical contract. This supports document/literal (wrapped and bare) and rpc/literal message styles.
2. Wrapper Synthesis: It automatically inserts any required SOAP wrapper elements as defined by the schema. For example, it wraps individual list items in their declared parent element, ensuring the backend receives a schema-valid envelope.
3. Cardinality and Requiredness: It enforces minOccurs and maxOccurs constraints from the XSD. If a required field is missing from the JSON request, the engine rejects the request with a validation error before it reaches the backend.
4. Type Coercion and Formatting: It coerces JSON values (booleans, numbers, strings) into their schema-defined SOAP types, including dates, times, and binary data. This process includes range and precision checks for numeric types and is influenced by configured conversion options.
5. Namespace and Prefix Policy: It emits the correct XML namespace for each element and allocates stable prefixes, preserving the semantic namespace URI.
6. Nullability: A JSON null value for a field defined as nillable="true" in the XSD is translated to an element with an xsi:nil="true" attribute. A null value for a non-nillable field results in a validation error.
7. Sequence Order: The engine preserves the element order defined in an xsd:sequence and enforces that exactly one branch of an xsd:choice is present.

In the "Consume" direction, this process is reversed: an inbound SOAP envelope is parsed and converted into an outbound REST request.

Response Mapping (SOAP → REST)

When receiving a SOAP response from the backend in the "Publish" direction, the engine produces a stable, typed JSON response:

1. Envelope and Wrapper Unwrapping: It strips the Envelope/Body/<OperationResponse> wrappers to expose the core payload. The exact elements to remove are determined by a recorded unwrapChain from the canonical contract.
2. Wrapper-Aware Collection Parsing: It correctly identifies and converts SOAP collections, including those with wrapper elements, into JSON arrays. The engine preserves the distinction between a null list and an empty list.
3. Type Coercion by Schema: It converts text-based values from the SOAP response into typed JSON fields (number, boolean, ISO-formatted date/time, etc.) according to the XSD schema 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 policy for its type.
   • A missing optional element is omitted from the JSON output by default.

The final structure of the JSON, including field casing, array formatting, and field order, is governed by the configured conversion options.

Fault Handling and Error 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) formats.

The shape of the resulting JSON error payload is controlled by the error-shape conversion option. The available shapes are:

• The platform's default error object.
• RFC 7807 Problem Details.
• A flat error body.
• The upstream fault detail payload, passed through unchanged.

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

Furthermore, any wsdl:fault messages defined in the WSDL are automatically reflected in the generated OpenAPI v3 specification, allowing API consumers to understand the contract for potential business errors.

Generated Rule Artifacts

The generated mapping is not a black box; it is an explicit and inspectable set of artifacts. Each artifact is stamped with the mapping engine version, contract version, contract parser version, and contract checksum for clear provenance.

The primary artifacts include:

• Request Mapping:
  • Records the root operation and input element.
  • Defines the wrapper policy.
  • Contains a rules[] list of compiled instructions, where each rule maps a fromJsonPath to a toSoapPath and includes metadata for type, coercion, requiredness, and namespace.
• Response Mapping:
  • Records the response root element.
  • Contains the unwrapChain[] specifying which SOAP wrappers to remove.
  • Contains a rules[] list of instructions, where each rule maps a fromSoapPath to a toJsonPath and includes metadata for type, coercion, null policy, and array policy.
• Fault Mapping:
  • Maintains a table for normalizing standard SOAP faults.
  • Can include an optional business-error extraction rule for identifying error information within a technically successful (e.g., HTTP 200) response.

Versioning and Immutability

Mappings are immutable and versioned. When a service version is activated, the platform uses a snapshot of its corresponding mapping.

Because all previous versions are retained, an API publisher can roll back to any prior version of a mapping at any time.

See Also

• Conversion options reference: A complete reference for all tunable conversion behaviors and their precedence.
• SOAP & XSD support: Details on supported SOAP versions, message styles, and XSD types.
• Field-level overrides: Instructions for manually changing the generated mapping for a specific field.
• Validation modes: Information on configuring validation behavior (e.g., enforce, monitor, off).
• Import a WSDL: Guidance on the first step of creating a service.
• Publish & version a service: How to manage the lifecycle of a published API.

All SOAP-to-REST docs