SOAP and XSD Support

Overview

This document provides a reference for the SOAP and WSDL/XSD features supported by the SOAP-to-REST conversion engine. It details the specific SOAP versions, message styles, XSD types, and fault models that the engine can parse and convert. This support applies automatically to the entire request and response message structure derived from an imported WSDL.

The conversion engine handles a wide range of mainstream SOAP and XSD constructs, enabling the transformation of complex SOAP services into RESTful APIs. The system detects the SOAP version at runtime, normalizes SOAP faults into configurable REST error formats, and preserves the semantic distinction between absent, null, and empty fields.

Each imported WSDL contract is captured as an immutable, versioned snapshot. This ensures that conversions are deterministic and that any changes to the backend WSDL are explicitly surfaced as a diff, preventing silent behavior changes.

How It Works

The conversion engine's support for SOAP and XSD is fundamental to both the initial WSDL import process and the runtime request/response transformation.

SOAP Version and WSDL Style Support

The platform supports both major SOAP versions on a single runtime. The engine automatically detects the version from the inbound request's Content-Type header and XML body, eliminating the need for manual configuration.

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

The inbound SOAP listener for the Consume direction (where the platform exposes a SOAP facade for a REST service) accepts both SOAP 1.1 and 1.2 requests.

The following WSDL message styles are supported:

• document/literal: Both wrapped and bare patterns are supported.
• rpc/literal: The engine can build and parse RPC-style SOAP envelopes.

RPC/encoded (SOAP Section-5 encoding) is not supported in the standard product.

Fault Handling

SOAP Faults are treated as first-class citizens and are not discarded. The engine intercepts <soap:Fault> elements from both SOAP 1.1 and 1.2 and normalizes them into a deterministic REST error object. API publishers can configure the structure of this error object using the error-shape conversion option. The available shapes are:

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

The HTTP status code returned to the API consumer is controlled by the upstream-failure-status conversion option. All wsdl:fault contracts declared in the WSDL are reflected in the generated OpenAPI v3 specification, allowing consumers to anticipate operation-specific error structures.

Namespace Handling

XML namespaces are preserved throughout the conversion process to maintain data integrity.

• Target namespaces, imported namespaces, and their corresponding URIs are maintained end-to-end.
• Namespace prefix allocation is stable, ensuring that the semantic mapping to namespace URIs does not change between operations.
• A Namespace repair feature at import time can correct missing or inconsistent namespace declarations in a WSDL, allowing otherwise invalid contracts to be onboarded successfully. Any repairs are noted in the import summary.

Null and Empty Value Semantics

The engine preserves the distinction between a field that is absent, explicitly null, or present but empty. This behavior is configurable.

• An element with xsi:nil="true" is round-tripped to and from a JSON null value, provided the schema defines the element as nillable="true".
• An attempt to send a null value for a non-nillable element results in a request-side validation error.
• An empty element (e.g., <field/>) is handled according to the configured null / empty handling policy for its data type.
• A missing optional element is omitted from the output by default.
• A required field that is also nillable is not incorrectly enforced as mandatory on the request side.

XSD Type Coverage

The conversion engine supports a comprehensive set of XSD schema constructs. The following table details the coverage for different categories of XSD features.

Category	What's handled
Scalar types	string, int, long, decimal, boolean, date, dateTime, duration, base64Binary, hexBinary, and the rest of the built-in simple types
Complex types	complexType; complexContent extension and restriction; simpleContent (scalar, and value-plus-attribute — #text + @attr)
Composition	sequence; choice, including multi-field branches counted as one selected branch (choice groups); all
Reuse / modularity	group and attributeGroup reference expansion; import, include, redefine (recursive, with cycle protection); external XSD resolution
Cardinality	minOccurs / maxOccurs; arrays and repeated/wrapped elements with item-element naming
Nullability	nillable="true" with xsi:nil round-tripping
Attributes & mixed content	XML attributes (@attr); mixed text-plus-element content (#text)
Substitution groups	substitutionGroup variant resolution
Polymorphism	xsi:type discriminator variants (variantsByXsiType), with configurable handling
Constraints / facets	enumeration, pattern (UTF-8 / Hebrew-aware regex), numeric bounds (minInclusive etc.), string-length facets
Advanced simple types	list, union (with per-item / per-member constraint metadata)
Wildcards	any / anyType wildcard passthrough
Identity constraints	xsd:key, xsd:keyref, xsd:unique metadata extraction
Multipart / external schema	multipart message parts; external schema resolution via import / include / redefine

Limitations and Scope

The following features are intentionally out of scope for the standard v1.0 product and are handled as bespoke engagements.

• RPC/encoded (SOAP Section-5 encoding): The supported styles are document/literal and rpc/literal.
• Inbound WS-Security: The product does not verify signatures or decrypt payloads for inbound SOAP requests arriving at its SOAP facade (Consume direction). However, the following outbound WS-Security features are supported for calls to a backend SOAP service (Publish direction):
  • UsernameToken (plaintext or digest)
  • wsu:Timestamp
  • X.509 BinarySecurityToken
  • JSR-105 XML Signature over the envelope
• Non-HTTP Transports: The platform supports HTTP and HTTPS only. Other transports like message queues or SFTP are not supported.

See Also

• How mapping works
• Conversion options reference
• Field-level overrides
• Import a WSDL
• Consume direction

---

All SOAP-to-REST docs