SOAP and XSD Support in API Conversion

Overview

This document provides a definitive reference for the SOAP and XML Schema Definition (XSD) features supported by the conversion engine. It details which SOAP versions, WSDL message styles, XSD types, and other contract features are automatically handled when converting a SOAP-based service to a RESTful interface.

The engine performs a full-field mapping, meaning the capabilities described here are applied automatically to the entire request and response structure as defined in the source WSDL. This ensures a comprehensive and predictable conversion without manual field-by-field mapping. This reference is intended for API publishers who need to understand whether a specific WSDL is compatible with the platform and how its features will be translated.

SOAP Versions and WSDL Message Styles

The platform is designed to handle the most common SOAP and WSDL constructs found in enterprise environments.

Supported SOAP Versions

The runtime supports both major SOAP versions. It automatically detects the version from the inbound request's Content-Type header and XML namespace, so no manual configuration is required to select a version. The WSDL import process also infers the version from the service binding.

• SOAP 1.1: Support includes the text/xml content type, the mandatory SOAPAction header, and the standard fault structure using <faultcode>, <faultstring>, and <detail>.
• SOAP 1.2: Support includes the application/soap+xml content type and the two-level fault structure with <Code>/<Value> and an optional <Subcode>.

Supported WSDL Message Styles

The conversion engine supports the following WSDL message styles:

• document/literal: Both wrapped and bare patterns are supported.
• rpc/literal: Supported, including the specific envelope structure for RPC-style messages.

The rpc/encoded style (also known as SOAP Section 5 encoding) is not supported by the standard product. See What's Out of Scope for more details.

XSD Type Coverage

The engine provides broad support for XSD 1.0 constructs, allowing for the accurate conversion of complex data contracts. The following table details the supported features.

Category	What's Handled
Scalar types	string, int, long, decimal, boolean, date, dateTime, duration, base64Binary, hexBinary, and other built-in simple types.
Complex types	complexType; complexContent with extension and restriction; simpleContent for both scalar values and values with attributes (#text + @attr).
Composition	sequence; choice (including multi-field choice groups); all.
Reuse / modularity	Expansion of group and attributeGroup references; recursive processing of import, include, and redefine with cycle protection; resolution of external XSDs.
Cardinality	minOccurs and maxOccurs for defining arrays and repeated elements, including wrapped elements with specific item names.
Nullability	nillable="true" with round-trip support for xsi:nil.
Attributes & mixed content	XML attributes (@attr) and mixed content models containing both text and elements (#text).
Substitution groups	Resolution of substitutionGroup variants.
Polymorphism	xsi:type for discriminating between variants, with configurable handling.
Constraints / facets	enumeration, pattern (with UTF-8 and Hebrew-aware regex), numeric bounds (minInclusive, etc.), and string-length facets.
Advanced simple types	list and union, including per-item/per-member constraint metadata.
Wildcards	Passthrough support for any and anyType.
Identity constraints	Metadata extraction for xsd:key, xsd:keyref, and xsd:unique.
Multipart / external schema	Handling of multipart message parts and resolution of external schemas via import, include, and redefine.

Each time a WSDL is imported, the parsed contract is stored as an immutable snapshot with a checksum and parser version. This ensures that re-importing the same WSDL yields a deterministic result and that any changes to the backend WSDL are surfaced as a detectable diff.

Fault Handling

SOAP faults are treated as a first-class part of the contract and are not ignored. The engine intercepts <soap:Fault> messages from the backend and normalizes them into a deterministic REST error response. This applies to both SOAP 1.1 (faultcode/faultstring/detail) and SOAP 1.2 (Code/Value/Subcode) faults.

The structure of the resulting JSON error payload is configurable via the error-shape conversion option, with the following choices:

• s2r-default: The platform's default error object.
• rfc7807: A standard RFC 7807 Problem Details object.
• flat: A simple, flat JSON object.
• upstream-passthrough: The backend's error payload, passed through without modification.

The HTTP status code returned to the client is controlled by the upstream-failure-status option. Faults declared in the WSDL using wsdl:fault are reflected in the generated OpenAPI v3 specification, allowing API consumers to anticipate error structures.

Namespace Handling

The platform correctly manages XML namespaces to ensure semantic integrity:

• Preservation: Target namespaces, imported namespaces, and their corresponding URIs are preserved end-to-end.
• Stable Prefixes: While XML prefixes are transient, the platform's allocation is stable and does not alter the underlying namespace URI mapping.
• Namespace Repair: During WSDL import, the parser can automatically repair common issues like missing or inconsistent namespace declarations. These repairs are noted in the import summary, allowing contracts that would otherwise fail parsing to be onboarded successfully.

Nullability and Empty Value Semantics

The engine preserves the distinction between absent, null, and empty values, which is critical for maintaining data integrity.

• An element marked with xsi:nil="true" in a SOAP message is converted to a JSON null value, and vice-versa.
• A request containing a null value for a non-nillable element will trigger a validation error.
• An empty element (e.g., <myField/>) is handled according to the configured policy for its type. See Null / Empty Handling.
• A missing optional field is omitted from the output by default.
• A required field that is also nillable="true" is correctly handled; its presence is not enforced if it is explicitly null.

What's Out of Scope

The standard v1.0 product focuses on common enterprise use cases. The following are considered out of scope for standard onboarding and are typically handled as bespoke engagements:

• RPC/encoded (SOAP Section-5 encoding): The platform supports document/literal and rpc/literal styles only.
• Inbound WS-Security: The platform does not verify inbound WS-Security signatures or decrypt encrypted payloads arriving at its SOAP facade (the Consume direction).
  • However, the platform does support outbound WS-Security signing for calls to a backend SOAP service (the Publish direction). This includes UsernameToken (plaintext or digest), wsu:Timestamp, X.509 BinarySecurityToken, and XML Signatures.
• Non-HTTP Transports: The platform supports HTTP and HTTPS exclusively. Transports like message queues or SFTP are not supported.

See Also

• How Mapping Works
• Conversion Options Reference
• Field-Level Overrides
• Import a WSDL

---

All SOAP-to-REST docs