SOAP-to-REST Conversion and Mapping Model

Overview

The conversion engine is the core component of the platform, responsible for bidirectional translation between REST/JSON and SOAP. Since v1.0, it supports two primary operational directions on a single runtime:

• Publish: Converts an inbound REST/JSON request into an outbound SOAP request, and the corresponding SOAP response back into a REST/JSON response. The published contract for API consumers is an OpenAPI v3 specification.
• Consume: Converts an inbound SOAP request into an outbound REST request, and the corresponding REST response back into a SOAP response. The published contract is a WSDL served at the consume endpoint.

The engine's mapping model is deterministic and full-field. This means that for a given WSDL/XSD contract, the mapping is generated automatically and covers every element in the request and response data structures. The process is predictable and repeatable, eliminating the need for manual mapping, custom mediation logic, or per-service code maintenance. This document explains the mechanics of this mapping model.

How it works

The conversion process is based on a compiled plan derived from an imported WSDL, not on heuristic rules executed at request time. This ensures low-latency conversion.

Canonical Contract Generation

When an API publisher imports a WSDL, the platform's parser materializes a canonical contract for each operation. This contract is an immutable, versioned snapshot of the full XSD tree for both the request and response messages. Each snapshot is stored with a checksum and the version of the parser that created it, ensuring a durable and auditable link between the source WSDL and the generated mapping.

Deterministic Full-Field Mapping

From the canonical contract, the platform generates an explicit, compiled mapping plan. This plan is cached for each active service operation version to minimize runtime overhead.

• Deterministic: The same canonical contract will always produce the exact same mapping rules. The same input payload will always produce the same output.
• Full-field: The mapping rules traverse the entire XSD tree, including wrappers, nested complex types, arrays, choices (xsd:choice), attributes, and mixed content. The mapping is comprehensive by default, not limited to a subset of fields.

Request Mapping (Publish Direction: REST to 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 resolves the operation's input message part to its corresponding element or type in the XSD, establishing the root of the data tree. This supports document/literal (wrapped and bare) and rpc/literal WSDL styles.
2. Wrapper Synthesis: It automatically inserts any required SOAP wrapper elements as defined in the schema. For example, it wraps individual list items in their declared parent element, ensuring the backend service receives a schema-valid envelope.
3. Cardinality & 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 service.
4. Type Coercion & Formatting: It coerces JSON values into their schema-defined SOAP types, including booleans, numerics (with range and precision checks), dates/times, and binary data. This behavior can be tuned with conversion options.
5. Namespace & Prefix Policy: It emits the correct XML namespace for each node and allocates stable prefixes, preserving the semantic namespace URI.
6. Nullability: A JSON null value for an element declared as nillable="true" in the XSD is translated into 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 Order: It preserves the element order defined by 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 (Publish Direction: SOAP to REST)

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

1. Envelope & Wrapper Unwrapping: It strips the Envelope/Body/<OperationResponse> wrappers to expose the core payload. The exact elements to be removed are determined by a pre-calculated unwrapChain recorded in the mapping artifact.
2. Wrapper-Aware Collection Parsing: It 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: It converts SOAP text values into typed JSON values (number, boolean, ISO-formatted date/time string, 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 null/empty policy for its type.
   • A missing optional element is omitted from the JSON object by default.

The final shape of the JSON, including field casing, array collapsing, and field ordering, is controlled by conversion options.

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) formats.

The shape of the resulting error payload is determined by the error-shape conversion option, which can be set to one of the following:

• The platform's default error object
• RFC 7807 Problem Details
• A flat error body
• The upstream 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's status or mask it (e.g., as a 200 OK).

Any wsdl:fault detail contracts declared in the WSDL are reflected in the generated OpenAPI v3 specification, allowing API consumers to understand the structure of potential error responses.

Generated Mapping Artifacts

The generated mapping is an explicit, inspectable artifact, not a black box. Each artifact contains:

• 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 rule, requiredness, and namespace.
• Response Mapping: Records the response root element, the unwrapChain[] used to strip SOAP wrappers, and a rules[] list. Each rule defines a mapping from a fromSoapPath to a toJsonPath with its associated type, coercion rule, null policy, and array policy.
• Fault Mapping: Contains the fault translation table and an optional business-error extraction rule for identifying error information within a technically successful (e.g., HTTP 200) response.

Every generated artifact is stamped with the mapping-engine version, contract version, contract parser version, and contract checksum for complete traceability.

Versioning and Immutability

Mappings are immutable and versioned. When an API publisher activates a service version, they are making a snapshot of its mapping live. Editing a configuration, such as a field override, creates a new revision of the service rather than mutating the active one. This model allows an operator to roll back to any prior version at any time.

Troubleshooting

The mapping engine can produce several types of errors based on schema validation and backend responses.

Condition	Trigger	Outcome
Missing Required Field	A JSON request is missing a field that corresponds to an XSD element with minOccurs greater than 0.	The request is rejected with a validation error before the backend call is made.
Invalid Null Value	A JSON request provides a null value for a field that corresponds to an XSD element that is not nillable="true".	The request is rejected with a validation error.
SOAP Fault	The upstream backend service returns a <soap:Fault> element in its response.	The fault is normalized into a REST error response. The shape and HTTP status code are determined by the error-shape and upstream-failure-status conversion options.
Business Error in Success Response	The backend returns a non-fault response (e.g., HTTP 200) that contains data indicating a business-level error.	By default, this is treated as a successful response. A business-error extraction rule can be configured in the fault mapping to identify and handle such cases.

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