Loading…
Loading…
A complete reference for all SOAP-to-REST conversion options. Control how dates, numbers, arrays, errors, and other values are transformed from SOAP to
When translating a SOAP-based service to a RESTful interface, there are numerous small but significant mismatches in data representation conventions. SOAP and REST disagree on formats for dates, the distinction between a single-element list and a scalar value, the representation of absent values, field naming conventions, and error body structures.
Conversion options are granular controls that allow an API publisher to define the precise transformation rules for these cases. Each option has a sensible platform default, but can be overridden to match the specific requirements of the backend service or the expectations of API consumers.
These options are configured in the platform UI under Settings → Conversion defaults for platform-wide settings, with more specific overrides available at the service, operation, or individual field level. The configuration choices are applied at runtime to transform request and response payloads. Critically, the generated OpenAPI v3 contract is updated to reflect these choices, ensuring that the published documentation always matches the live API behavior.
Every conversion option is resolved through a fixed precedence chain, where the most specific setting always wins. The runtime engine evaluates this hierarchy for each API call to determine which rule to apply.
The resolution path proceeds from the broadest setting (System default) to the most specific (per-Field), with a hardcoded fallback as the final step.
flowchart TD
A[System Default] --> B{Service Override};
B --> C{Operation Override};
C --> D{Field Override};
D --> E[(Hardcoded Fallback)];
style A fill:#f9f9f9,stroke:#333,stroke-width:2px
style B fill:#f9f9f9,stroke:#333,stroke-width:2px
style C fill:#f9f9f9,stroke:#333,stroke-width:2px
style D fill:#f9f9f9,stroke:#333,stroke-width:2px
style E fill:#f9f9f9,stroke:#333,stroke-width:2pxIMPORTANT
The available override tiers are not uniform across all options.
request-validation and response-validation modes have a true per-Service override. For all other options, the most granular non-field override is per-Operation.response envelope wrap, error/fault shape, JSON field ordering, and SOAP header propagation—cannot be set on a per-field basis. They are configurable at the System and Operation levels only.Per-field overrides are configured within the field mapping UI.
The following conversion options are exposed by the runtime. The defaults listed are the system-level platform defaults.
| Controls | How xsd:date and xsd:dateTime values are rendered in JSON. |
| Modes | iso-8601-utc (default), iso-8601-utc-strict, iso-8601-local, iso-8601-offset, epoch-millis, epoch-seconds, custom |
| Tiers | System → Operation → Field |
| Companion Sub-fields | Custom pattern: A string used when format is custom.<br>Timezone: utc (default), local, passthrough.<br>Local timezone: An IANA zone ID (e.g., Asia/Jerusalem) used when timezone is local.<br>Nil value representation: omit (default), null. |
Nil Value Representation
This setting determines how an empty or absent date/time value is represented in the REST response. It is a specific control for date/time types, distinct from the general Null / empty handling option.
omit (default): The key for the date/time field is completely removed from the JSON object. This is the back-compatible default and is recommended for clients that reject null values. In the OpenAPI spec, the field is marked as optional but not nullable.null: The key is present in the JSON object with a value of null. Use this for consumers with fixed-shape schemas or typed deserializers that need to distinguish between an absent field and a null one. In the OpenAPI spec, this marks the field as nullable: true.This option applies only to xsd:dateTime, xsd:date, and xsd:time types.
| Controls | How numbers are rendered, especially large integers that may exceed safe JSON precision. |
| Modes | as-number (default), as-string, as-string-when-unsafe (renders as a number unless it exceeds JSON-safe integer precision, then renders as a string) |
| Tiers | System → Operation → Field |
| Controls | How boolean values are represented in JSON. |
| Modes | as-bool (default, uses JSON true/false), as-int (uses 1/0) |
| Tiers | System → Operation → Field |
| Direction Model | Bidirectional. Separate overrides can be configured for the request and response directions. |
| Controls | How an absent, xsi:nil, or empty value from the SOAP payload is represented in JSON. |
| Modes | as-null, as-empty-value, omit-field |
| Defaults | Request side: omit-field.<br>Response side: as-null. |
| Tiers | System → Operation → Field |
| Direction Model | Bidirectional. Separate settings are maintained for request and response transformations. |
| Controls | How a list containing a single element is represented in JSON. |
| Modes | always-array (default, a single-element list renders as a JSON array), collapse-when-single (a single-element list renders as a scalar value) |
| Tiers | System → Operation → Field (Response side only) |
| Controls | Text trimming and normalization for string values. |
| Modes | preserve (default), trim, collapse (collapses internal whitespace runs), trim-ascii-only, collapse-ascii-only |
| Tiers | System → Operation → Field (Response side only) |
NOTE
The *-ascii-only modes are opt-in variants that only normalize ASCII whitespace characters, leaving non-ASCII whitespace (such as that found in some non-Latin scripts) untouched.
| Controls | How xsd:base64Binary and xsd:hexBinary members are rendered. |
| Modes | passthrough (default), base64, hex, data-url |
| Tiers | System → Operation → Field (Response side only) |
| Companion Sub-field | Data-URL MIME type: A string specifying the MIME type when mode is data-url. |
| Controls | How xsd:duration values are rendered. |
| Modes | passthrough (default, renders as an ISO-8601 duration string), seconds (renders as total seconds), components (renders as a {days, hours, minutes, seconds} object) |
| Tiers | System → Operation → Field (Response side only) |
| Controls | The behavior when a field marked as required is empty in the backend response. |
| Modes | permissive (default), fail-with-502 |
| Tiers | System → Operation → Field (Response side only) |
| Controls | The naming convention for JSON field names in the response. |
| Modes | as-source (default), camelCase, snake_case, kebab-case, PascalCase |
| Tiers | System → Operation → Field (Response side only) |
xsi:type discriminator| Controls | How a polymorphic xsi:type attribute from the SOAP payload is represented in JSON. |
| Modes | strip (default, drops the type hint), keep-as-meta (retains the type as metadata), discriminator-field (emits the type as a named field) |
| Tiers | System → Operation → Field (Response side only) |
| Companion Sub-field | Discriminator field name: A string specifying the field name when mode is discriminator-field. |
| Controls | The top-level structure of the REST response body. |
| Modes | raw (default, the payload is the root of the response), data-key-only (payload is nested under a data key), wrapped-with-meta (payload is nested alongside a metadata block) |
| Tiers | System → Operation |
| Controls | The JSON structure of a non-2xx or SOAP Fault response. |
| Modes | s2r-default (default), rfc7807 (formats as RFC 7807 Problem Details), flat, upstream-passthrough (sends the backend's error payload verbatim) |
| Tiers | System → Operation |
| Controls | The order of keys in the response JSON object. |
| Modes | as-schema (default, follows the order declared in the XSD), alphabetical, preserve-source (follows the order returned by the backend) |
| Tiers | System → Operation |
| Controls | How content from the inbound <soap:Header> is handled. |
| Modes | drop (default, with a denylist for Security headers), expose-as-meta (includes headers in response metadata), expose-as-http-headers |
| Tiers | System → Operation |
| Controls | How much detail from a backend <soap:Fault> is exposed to the API consumer. This specifically affects fields that often contain internal details like stack traces or hostnames (faultActor, faultNode, faultRole, detail). |
| Modes | safe (default, strips backend-identifying details, keeping only client-safe fields like faultCode and faultString), full (passes through the fault verbatim) |
| Tiers | System → Operation |
WARNING
This is a security control, not just a formatting option. Setting the mode to full is an explicit operator opt-in to expose potentially sensitive backend information. The full, raw SOAP response, including the complete fault, is always available to operators in the structured trace, regardless of this setting.
| Controls | Whether the outbound call to the backend SOAP service is sent as inline XML or using MTOM. |
| Modes | off (default, sends as text/xml or application/soap+xml), on (sends as multipart/related with xop:Include for backends that require MTOM) |
| Tiers | System default only. The source notes that a per-operation override is a planned enhancement. |
| Controls | The HTTP status code returned to the client when the backend service returns a failure. |
| Modes | propagate (default, maps the SOAP fault to an appropriate 4xx or 5xx status), mask-as-200 (returns HTTP 200 OK with the fault details in the response body) |
| Tiers | System → Operation |
| Controls | The level of contract enforcement for inbound requests from the API consumer. |
| Modes | off, shadow (default, logs validation failures but does not reject the request), enforce (rejects requests that do not conform to the contract) |
| Tiers | System → Service |
| Controls | The level of contract checking for responses from the backend SOAP service. |
| Modes | off, monitor (default, logs validation failures but does not reject the response), enforce (rejects non-conforming responses from the backend) |
| Tiers | System → Service |
| Controls | Whether the generated OpenAPI specification includes synthetic minimum and maximum bounds for int32/int64 fields. |
| Modes | emit (default), omit |
| Tiers | System → Operation → Field |
NOTE
This is a documentation-only setting. It affects the content of the generated OpenAPI spec but has no effect on runtime payload conversion.
One related setting is applied only once during service onboarding and is not a dynamic runtime option.
pattern facet during the initial mapping generation.
notify-only (default), notify-and-suggest, auto-apply-silent, none.Understanding conversion options can help diagnose unexpected API behavior.
fail-with-502, the gateway will return a 502 error if a field marked as required in the mapping is absent or empty in the backend's SOAP response.mask-as-200, SOAP faults from the backend will be returned to the client with an HTTP 200 status code, with the error details contained within the response body. This can be confusing for clients expecting to rely on HTTP status codes for error detection.full, internal backend details like stack traces or hostnames may be exposed to API consumers. For security, the default safe mode should be used unless this exposure is explicitly intended.enforce, any message that does not strictly conform to the OpenAPI contract will be rejected with a 4xx or 5xx error, respectively. Use shadow or monitor mode to log violations without rejecting traffic.