A complete reference for all SOAP-to-REST conversion options, their modes, defaults, and resolution hierarchy for precise data transformation.
Applies to1.7.1
Overview
Conversion options are granular settings that control how the platform translates data between a SOAP backend's XML format and the REST API's JSON format. They exist to resolve the common mismatches between SOAP and REST conventions, such as date/time formatting, null value representation, array handling, and field naming styles.
API publishers configure these options to precisely shape the JSON payload and behavior of the REST API. Each option has a sensible platform default, which can be overridden at progressively more specific levels: for an entire service, for a single operation, or even for an individual field.
These settings are applied in two places simultaneously:
At runtime, to transform live request and response payloads.
In the generated OpenAPI v3 specification, to ensure the published API contract accurately reflects the runtime behavior.
This document provides a canonical reference for every available conversion option, its available modes, and its resolution logic.
How it works: The Resolution Hierarchy
Every conversion option is resolved through a fixed precedence chain. The most specific setting always wins. If no override is set at a given level, the system falls back to the next broader level.
flowchart LR
subgraph Resolution Hierarchy
direction LR
A[System Default] --> B[per-Service Override] --> C[per-Operation Override] --> D[per-Field Override]
end
style A stroke-width:2px
style D stroke-width:2px
IMPORTANT
The available override tiers are not the same for all options.
Per-Service vs. Per-Operation: Most runtime conversion options are configured at the System or per-Operation level. Only the request-validation and response-validation options have a true per-Service override tier. For all other options, the effective service-level configuration is done per-operation.
Body-Level Options: Options that affect the entire request or response body do not have a per-Field override tier. These include response envelope wrap, error/fault shape, JSON field ordering, and SOAP header propagation.
Configuration is managed in the platform UI under Settings → Conversion defaults for platform-wide settings, with overrides available on the configuration pages for specific services, operations, and fields.
Conversion Option Catalog
The following sections detail every runtime conversion option. The specified defaults are the initial platform-wide (system) defaults.
Date / time
Controls how xsd:date and xsd:dateTime values from the SOAP service are rendered in the JSON payload.
Property
Value
Tiers
System → Operation → Field
Default Format
iso-8601-utc
Modes
Mode
Description
iso-8601-utc
Renders as an ISO-8601 string in UTC.
iso-8601-utc-strict
A stricter variant of iso-8601-utc.
iso-8601-local
Renders as an ISO-8601 string in the configured local timezone.
iso-8601-offset
Renders as an ISO-8601 string including the original timezone offset.
epoch-millis
Renders as the number of milliseconds since the Unix epoch.
epoch-seconds
Renders as the number of seconds since the Unix epoch.
custom
Renders using a custom-defined format pattern.
Companion Sub-fields
Field
Description
Custom pattern
The format string to use when format is custom.
Timezone
utc (default), local, or passthrough.
Local timezone
An IANA timezone ID (e.g., Asia/Jerusalem) used when Timezone is local.
Nil value representation
omit (default) or null. Controls whether an absent date value is omitted from the JSON or included as null. This is distinct from the global Null / empty handling option. omit results in an optional field in the OpenAPI spec, while null adds nullable: true.
Numeric handling
Controls how numeric values are rendered, with special handling for large integers that may exceed the precision limits of standard JSON numbers.
Property
Value
Tiers
System → Operation → Field
Default Mode
as-number
Modes
Mode
Description
as-number
(Default) Renders all numeric values as JSON numbers.
as-string
Renders all numeric values as JSON strings.
as-string-when-unsafe
Renders numbers as JSON numbers, but converts any integer that exceeds JSON-safe precision (Number.MAX_SAFE_INTEGER) to a JSON string to prevent data loss.
Boolean handling
Controls the JSON representation of boolean values.
Property
Value
Tiers
System → Operation → Field
Default Mode
as-bool
Direction
Bidirectional. Separate overrides can be set for the request and response directions.
Modes
Mode
Description
as-bool
(Default) Renders as JSON boolean literals (true/false).
as-int
Renders as JSON numbers (1/0).
Null / empty handling
Controls how absent, xsi:nil, or empty values in the SOAP payload are represented in JSON.
Property
Value
Tiers
System → Operation → Field
Defaults
Request: omit-field. Response: as-null.
Direction
Bidirectional. Separate settings are applied for request and response transformations.
Modes
Mode
Description
as-null
Represents the value as a JSON null.
as-empty-value
Represents the value as a type-appropriate empty value (e.g., "" for a string, 0 for a number).
omit-field
The key is omitted entirely from the JSON object.
Array collapse
Controls the representation of lists that contain only a single element.
Property
Value
Tiers
System → Operation → Field (Response side only)
Default Mode
always-array
Modes
Mode
Description
always-array
(Default) A single-element list is always rendered as a JSON array (e.g., [ "item" ]).
collapse-when-single
A single-element list is rendered as a scalar value (e.g., "item").
Whitespace handling
Controls the normalization and trimming of whitespace in text values.
Property
Value
Tiers
System → Operation → Field (Response side only)
Default Mode
preserve
Modes
Mode
Description
preserve
(Default) All original whitespace is kept.
trim
Leading and trailing whitespace is removed.
collapse
Internal runs of whitespace are collapsed into a single space, and leading/trailing whitespace is trimmed.
trim-ascii-only
Same as trim, but only affects ASCII whitespace characters.
collapse-ascii-only
Same as collapse, but only affects ASCII whitespace characters.
Binary encoding
Controls how binary data types (xsd:base64Binary, xsd:hexBinary) are rendered in JSON.
Property
Value
Tiers
System → Operation → Field (Response side only)
Default Mode
passthrough
Modes
Mode
Description
passthrough
(Default) The binary data is passed through in its original encoding (Base64 or Hex).
base64
Forces the output to be Base64 encoded.
hex
Forces the output to be Hex encoded.
data-url
Renders the binary data as a Data URL (data:[<mediatype>];base64,<data>).
Companion Sub-fields
Field
Description
Data-URL MIME type
The MIME type to use when mode is data-url.
Duration
Controls how xsd:duration values are rendered in JSON.
Property
Value
Tiers
System → Operation → Field (Response side only)
Default Mode
passthrough
Modes
Mode
Description
passthrough
(Default) Renders as an ISO-8601 duration string (e.g., P3Y6M4DT12H30M5S).
seconds
Renders as the total number of seconds.
components
Renders as a JSON object with keys for days, hours, minutes, and seconds.
Required handling
Controls runtime behavior when a field marked as required in the schema is empty in the backend response.
Property
Value
Tiers
System → Operation → Field (Response side only)
Default Mode
permissive
Modes
Mode
Description
permissive
(Default) Allows the empty value to pass through, subject to Null / empty handling rules.
fail-with-502
The gateway rejects the response and returns an HTTP 502 Bad Gateway error to the client.
Field-name casing
Controls the naming convention (casing) of field names in the JSON output.
Property
Value
Tiers
System → Operation → Field (Response side only)
Default Mode
as-source
Modes
Mode
Description
as-source
(Default) Field names are kept exactly as they are in the source WSDL/XSD.
camelCase
Converts field names to camelCase.
snake_case
Converts field names to snake_case.
kebab-case
Converts field names to kebab-case.
PascalCase
Converts field names to PascalCase.
xsi:type discriminator
Controls how polymorphic type information, specified via the xsi:type attribute in XML, is represented in JSON.
Property
Value
Tiers
System → Operation → Field (Response side only)
Default Mode
strip
Modes
Mode
Description
strip
(Default) The xsi:type information is discarded.
keep-as-meta
The type information is preserved in a metadata block.
discriminator-field
The type information is emitted as a new field in the JSON object.
Companion Sub-fields
Field
Description
Discriminator field name
The name of the field to use when mode is discriminator-field.
Response envelope wrap
A body-level option that controls the overall structure of the JSON response body.
Property
Value
Tiers
System → Operation
Default Mode
raw
Modes
Mode
Description
raw
(Default) The response body contains the core payload directly.
data-key-only
The core payload is nested under a top-level data key.
wrapped-with-meta
The response body contains the payload along with a metadata block.
Error / fault shape
A body-level option that defines the JSON structure for non-2xx or SOAP Fault responses.
Property
Value
Tiers
System → Operation
Default Mode
s2r-default
Modes
Mode
Description
s2r-default
(Default) The platform's standard error shape.
rfc7807
Formats the error according to RFC 7807 Problem Details for HTTP APIs.
flat
A simple, flat JSON object error structure.
upstream-passthrough
The backend's error payload is passed through to the client without modification.
JSON field ordering
A body-level option that controls the order of keys in the final JSON response body.
Property
Value
Tiers
System → Operation
Default Mode
as-schema
Modes
Mode
Description
as-schema
(Default) Fields are ordered as they are declared in the source XSD.
alphabetical
Fields are ordered alphabetically by key.
preserve-source
Fields are ordered as they were received from the backend SOAP service.
SOAP header propagation
A body-level option that controls how inbound <soap:Header> blocks are handled.
Property
Value
Tiers
System → Operation
Default Mode
drop
Modes
Mode
Description
drop
(Default) SOAP headers are dropped. Headers on a security denylist (e.g., <Security>) are always dropped.
expose-as-meta
Header content is exposed in a metadata block in the JSON response.
expose-as-http-headers
Header content is mapped to HTTP response headers.
SOAP fault-detail exposure
A body-level security option that controls how much detail from a backend <soap:Fault> is exposed to the API consumer.
Property
Value
Tiers
System → Operation
Default Mode
safe
WARNING
This is a security-sensitive setting. The full mode can expose internal system details like stack traces and hostnames from the backend. Use it only when you have explicitly assessed the risk. The full, raw SOAP fault is always available to operators in the structured trace, regardless of this setting.
Modes
Mode
Description
safe
(Default) Strips potentially sensitive, free-text fields (faultActor, faultNode, faultRole, detail) from the fault. Only client-safe fields (faultCode, faultString, faultSubcode) are passed through.
full
Passes the entire backend fault through verbatim. This requires an explicit operator opt-in.
Outbound MTOM / XOP request
A transport-level option that controls whether the request to the backend SOAP service is sent using MTOM (Message Transmission Optimization Mechanism).
Property
Value
Tiers
System default only. The source notes a per-operation override is a planned follow-up.
Default Mode
off
Modes
Mode
Description
off
(Default) The SOAP request is sent inline as text/xml or application/soap+xml.
on
The request is sent as a multipart/related message with binary content attached via xop:Include. Use this for backends that require MTOM.
Upstream failure status
Controls the HTTP status code returned to the API consumer when the backend service returns a failure (e.g., a SOAP Fault).
Property
Value
Tiers
System → Operation
Default Mode
propagate
Modes
Mode
Description
propagate
(Default) The backend fault is mapped to an appropriate HTTP 4xx or 5xx status code.
mask-as-200
The gateway returns an HTTP 200 OK status, with the fault details contained within the response body.
Request validation mode
Controls the enforcement of the API contract for inbound requests from the API consumer.
Property
Value
Tiers
System → Service
Default Mode
shadow
Modes
Mode
Description
off
Validation is disabled.
shadow
(Default) Requests are validated, and any failures are logged, but the request is not rejected. This allows you to preview the impact of enforcement.
enforce
Non-conforming requests are rejected with an error.
Response validation mode
Controls contract checking of the response received from the backend SOAP service.
Property
Value
Tiers
System → Service
Default Mode
monitor
Modes
Mode
Description
off
Validation is disabled.
monitor
(Default) Responses are validated, and any failures are logged, but the response is not rejected.
enforce
Non-conforming responses are rejected, resulting in an error to the API consumer.
Integer range bounds
A documentation-only option that controls whether synthetic minimum and maximum bounds for int32/int64 types are included in the generated OpenAPI specification. This setting does not affect runtime behavior.
Property
Value
Tiers
System → Operation → Field
Default Mode
emit
Modes
Mode
Description
emit
(Default) The OpenAPI specification will include minimum and maximum properties on integer fields.
omit
The minimum and maximum properties are omitted from the specification.
Onboarding-Time Setting
One additional setting is related to conversion but is applied once during service onboarding, not on a per-request basis at runtime.
String fields without a validation regex: This setting governs how the platform handles string fields from the XSD that lack a pattern facet.
Description: This is not a runtime knob and is not resolved per-call. It influences the initial mapping generation process.
Troubleshooting
Understanding conversion options can help diagnose unexpected API behavior.
Unexpected null values or missing fields: Check the Null / empty handling and Date / time (Nil value representation) options. The defaults differ for requests and responses.
Receiving a 502 Bad Gateway error: This can be triggered by the Required handling option if it is set to fail-with-502 and the backend returns an empty value for a required field.
Receiving a 4xx error on requests: If the Request validation mode is set to enforce, your request may be failing schema validation. Check the shadow mode logs to see potential validation issues without blocking requests.
Backend error details are missing: The SOAP fault-detail exposure option defaults to safe, which strips potentially sensitive information from backend faults. To see the full fault, it must be explicitly set to full.
Backend failure returns an HTTP 200 OK: This occurs when the Upstream failure status option is set to mask-as-200. The error details will be in the response body.
