Loading…
Loading…
Reference for SOAP and XSD support in the API conversion engine. Covers SOAP 1.1/1.2, WSDL styles, XSD type coverage, fault handling, and nullability
This document provides a reference for the SOAP and XML Schema Definition (XSD) capabilities of the conversion engine. It details supported SOAP versions, WSDL message styles, XSD data types, and the handling of faults, namespaces, and null values. This information is intended for engineers operating the conversion platform to understand its scope and behavior when transforming SOAP-based services into RESTful APIs.
The conversion engine applies this support across the entire request and response data structure as defined in the WSDL, a process known as full-field mapping. When a WSDL is imported, its contract is parsed and stored as an immutable, versioned snapshot with a checksum. This ensures that regeneration is deterministic and that any changes to the backend WSDL are surfaced as a detectable difference rather than a silent change in behavior.
The conversion engine processes inbound SOAP requests and WSDL definitions through a series of automated steps to ensure accurate and consistent transformation.
The runtime automatically detects whether an incoming request uses SOAP 1.1 or SOAP 1.2. It determines the version by inspecting the request's Content-Type header (text/xml for 1.1, application/soap+xml for 1.2) and the request body's XML namespace. This detection happens on the wire, requiring no manual configuration for the conversion to function correctly. The WSDL import process also infers the SOAP version from the service binding.
When a backend SOAP service returns a <soap:Fault>, the engine intercepts it and normalizes it into a deterministic REST error structure. It correctly interprets both SOAP 1.1 faults (faultcode, faultstring, detail) and SOAP 1.2 faults (two-level Code/Value and Subcode). The final shape of the REST error response and the resulting HTTP status code are configurable via conversion options. WSDL-declared faults (wsdl:fault) are also reflected in the generated OpenAPI v3 specification, making error contracts visible to API consumers.
The engine preserves namespace URIs end-to-end and maintains stable prefix allocation. During WSDL import, it can perform namespace repair to correct missing or inconsistent namespace declarations, allowing contracts that would otherwise fail to parse to be onboarded successfully. Any repairs are noted in the import summary. The engine also recursively resolves external schemas referenced via import, include, and redefine, with built-in cycle protection.
The system distinguishes between absent fields, explicitly null fields, and empty fields, preserving this semantic detail during transformation.
xsi:nil="true" is round-tripped to a JSON null.<x/>) is determined by a configurable policy based on the element's data type.The platform supports both major SOAP versions and common WSDL message styles on a single runtime.
faultcode/faultstring/detail fault model, the mandatory SOAPAction header, and the Content-Type: text/xml header.application/soap+xml content type and the two-level fault model using Code/Value and an optional Subcode.The SOAP listener for inbound SOAP-facade conversions (Consume direction) accepts both SOAP 1.1 and 1.2 requests.
The rpc/encoded style (SOAP Section-5 encoding) is not supported in the standard product.
The conversion engine provides comprehensive support for a wide range of XSD constructs.
| 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 (extension and restriction); simpleContent (scalar, and value-plus-attribute as #text + @attr). |
| Composition | sequence; choice (including multi-field branches); 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. |
SOAP faults are treated as first-class citizens and are transformed into a consistent REST error model. A <soap:Fault> from the backend is normalized into a REST error response. The specific structure of this response is configurable using the error-shape conversion option, with choices including:
s2r-default: The platform's default error object.rfc7807: A standard RFC 7807 Problem Details object.flat: A flat error body.upstream-passthrough: The original error payload from the upstream service, passed through without modification.The HTTP status code for the failure is controlled by the upstream-failure-status option. Additionally, business-error nodes within an otherwise successful SOAP response can be mapped to the standard error model through configuration.
nillable="true" in the schema will trigger a validation error on the request side. This prevents the generation of an invalid SOAP envelope.minOccurs="1") and nillable="true" will not be incorrectly enforced as required if it is absent from the request.The following features are not included in the standard v1.0 product and are typically handled as bespoke engagements: