A comprehensive reference for all conversion options that control how SOAP data is transformed into REST/JSON, including data types, naming, and error
## Overview
When transforming SOAP services into REST APIs, there are numerous small but significant differences in convention between the two protocols. These include representations for dates, booleans, null values, arrays, field names, and error structures.
**Conversion options** provide granular control over these transformations, allowing an API publisher to define the precise behavior of the REST interface. While the platform provides sensible defaults, every option is configurable to meet specific consumer requirements or backend constraints.
Options can be set globally at **Settings → Conversion defaults**, and then overridden for specific services, operations, or even individual fields. The generated OpenAPI v3 contract automatically reflects these choices, ensuring that the runtime behavior and the published documentation are always synchronized.
## How Options are Resolved
Every conversion option is resolved through a fixed precedence chain, where the most specific setting for a given request always wins.
```mermaid
flowchart TD
subgraph "Option Resolution Precedence"
A["System Default (Broadest)"] --> B["Per-Service Override"];
B --> C["Per-Operation Override"];
C --> D["Per-Field Override (Most Specific)"];
D --> F["(Hardcoded Fallback)"];
end
IMPORTANT
Not all options are available at all tiers:
Per-Service vs. Per-Operation: Most runtime conversion options are configurable at the System and Operation levels. Only the request-validation and response-validation modes have a true per-Service override tier. For all other options, the most granular non-field override is per-Operation.
Body-Level Options: Options that affect the entire request or response body do not have a per-Field override tier, as they are not attached to a single field. These include response envelope wrap, error/fault shape, JSON field ordering, and SOAP header propagation.
Per-field overrides are configured in the data mapping user interface.
Option Catalog
The following conversion options are available. Defaults shown are the system-level platform defaults.
Date / time
Property
Description
What it controls
How xsd:date and xsd:dateTime values are rendered in JSON.
Custom pattern: A format string used only when format is custom.<br/>Timezone: utc (default), local, passthrough.<br/>Local timezone: An IANA zone ID (e.g., Asia/Jerusalem); used only when timezone is local.<br/>Nil value representation: omit (default), null.
Tiers
System → Operation → Field
The Nil value representation sub-field controls how an empty or absent date/time value is represented in the JSON payload:
omit (default): The key for the date/time field is omitted from the JSON object. This is compatible with clients that reject null values. In the OpenAPI spec, the field is marked as optional.
null: The key is present with a JSON null value. Use this for consumers that expect a fixed schema shape. In the OpenAPI spec, the field is marked nullable: true.
Numeric handling
Property
Description
What it controls
How numbers are rendered, particularly large integers that may exceed safe JSON precision.
Modes
as-number (default)<br/>as-string<br/>as-string-when-unsafe (renders as a number unless it exceeds JSON-safe integer precision, then renders as a string)
Tiers
System → Operation → Field
Boolean handling
Property
Description
What it controls
How boolean values are represented in JSON.
Modes
as-bool (default): Renders as JSON true/false.<br/>as-int: Renders as 1/0.
Tiers
System → Operation → Field
Direction
Bidirectional. Separate overrides can be configured for the request and response directions.
Null / empty handling
Property
Description
What it controls
How an absent, xsi:nil, or empty value from the SOAP payload is represented in JSON.
Bidirectional. Separate options are configured for the request and response directions.
Array collapse
Property
Description
What it controls
How a list containing a single element is represented in the JSON response.
Modes
always-array (default): A single-element list is rendered as a JSON array.<br/>collapse-when-single: A single-element list is rendered as a scalar value.
Tiers
System → Operation → Field (Response side only)
Whitespace handling
Property
Description
What it controls
Text trimming and normalization in the JSON response.
Modes
preserve (default): No changes to whitespace.<br/>trim: Removes leading/trailing whitespace.<br/>collapse: Collapses internal runs of whitespace.<br/>trim-ascii-only: trim for ASCII whitespace only.<br/>collapse-ascii-only: collapse for ASCII whitespace only.
Tiers
System → Operation → Field (Response side only)
Binary encoding
Property
Description
What it controls
How xsd:base64Binary and xsd:hexBinary members are rendered in the JSON response.
Modes
passthrough (default), base64, hex, data-url
Companion sub-field
Data-URL MIME type: Specifies the MIME type when mode is data-url.
Tiers
System → Operation → Field (Response side only)
Duration
Property
Description
What it controls
How xsd:duration values are rendered in the JSON response.
Modes
passthrough (default): Renders as an ISO-8601 duration string.<br/>seconds: Renders as the total number of seconds.<br/>components: Renders as a JSON object with {days, hours, minutes, seconds}.
Tiers
System → Operation → Field (Response side only)
Required handling
Property
Description
What it controls
The behavior when a required field is absent in the backend response.
Modes
permissive (default): Allows the response to proceed.<br/>fail-with-502: The gateway returns an HTTP 502 Bad Gateway error.
Tiers
System → Operation → Field (Response side only)
Field-name casing
Property
Description
What it controls
The naming convention for field names in the JSON response.
Modes
as-source (default): Uses the name from the source WSDL/XSD.<br/>camelCase<br/>snake_case<br/>kebab-case<br/>PascalCase
Tiers
System → Operation → Field (Response side only)
xsi:type discriminator
Property
Description
What it controls
How a polymorphic xsi:type attribute from the SOAP payload is represented in the JSON response.
Modes
strip (default): The type information is dropped.<br/>keep-as-meta: The type is kept as metadata.<br/>discriminator-field: The type is emitted as a named field in the JSON object.
Companion sub-field
Discriminator field name: Specifies the name of the field when mode is discriminator-field.
Tiers
System → Operation → Field (Response side only)
Response envelope wrap (Body-Level)
Property
Description
What it controls
The top-level structure of the REST response body.
Modes
raw (default): The response body contains the payload directly.<br/>data-key-only: The payload is nested under a data key.<br/>wrapped-with-meta: The response body contains the payload plus a metadata block.
Tiers
System → Operation
Error / fault shape (Body-Level)
Property
Description
What it controls
The JSON structure of a non-2xx or SOAP Fault response.
Modes
s2r-default (default)<br/>rfc7807 (RFC 7807 Problem Details format)<br/>flat<br/>upstream-passthrough (The backend's error payload is passed through unchanged)
Tiers
System → Operation
JSON field ordering (Body-Level)
Property
Description
What it controls
The order of keys in the JSON response body.
Modes
as-schema (default): Follows the order declared in the source XSD.<br/>alphabetical<br/>preserve-source: Follows the order returned by the backend service.
Tiers
System → Operation
SOAP header propagation (Body-Level)
Property
Description
What it controls
How content from the inbound <soap:Header> block is handled.
Modes
drop (default): Headers are dropped, with a denylist for Security headers.<br/>expose-as-meta: Headers are included in the response metadata.<br/>expose-as-http-headers: Headers are mapped to HTTP response headers.
Tiers
System → Operation
SOAP fault-detail exposure (Body-Level, Security)
Property
Description
What it controls
How much detail from a backend <soap:Fault> is exposed to the API consumer.
Modes
safe (default): Strips backend-identifying and free-text fields (faultActor, faultNode, faultRole, detail), keeping only client-safe codes and strings.<br/>full: Passes the entire fault through verbatim. This requires an explicit operator opt-in.
Tiers
System → Operation
WARNING
This is a security control, not a data conversion option. Setting this to full may expose sensitive backend details like stack traces and internal hostnames to the API consumer. The safe default is strongly recommended. The full fault detail is always available to operators in the structured trace, regardless of this setting.
Outbound MTOM / XOP request (Transport)
Property
Description
What it controls
Whether the request to the backend SOAP service is sent inline or using MTOM/XOP.
Modes
off (default): Sends as inline text/xml or application/soap+xml.<br/>on: Sends as multipart/related with xop:Include for backends that require MTOM.
Tiers
System default only.
Upstream failure status
Property
Description
What it controls
The HTTP status code returned to the API consumer when the backend service fails.
Modes
propagate (default): Maps the backend fault to an appropriate 4xx or 5xx HTTP status code.<br/>mask-as-200: Returns an HTTP 200 OK status with the fault details in the response body.
Tiers
System → Operation
Request validation mode
Property
Description
What it controls
The level of contract enforcement for inbound requests from API consumers.
Modes
off: No validation.<br/>shadow (default): Logs requests that would fail validation but does not reject them.<br/>enforce: Rejects requests that do not conform to the contract.
Tiers
System → Service
Response validation mode
Property
Description
What it controls
The level of contract checking for responses from the backend SOAP service.
Modes
off: No validation.<br/>monitor (default): Logs responses that would fail validation but does not reject them.<br/>enforce: Rejects non-conforming responses from the backend.
Tiers
System → Service
Integer range bounds (Spec-Emission Only)
Property
Description
What it controls
Whether the generated OpenAPI specification includes synthetic minimum and maximum bounds for int32/int64 fields.
Modes
emit (default): Adds bounds to the OpenAPI spec.<br/>omit: Does not add bounds.
Tiers
System → Operation → Field
NOTE
This option affects only the generated OpenAPI specification. It has no effect on runtime payload conversion.
Spec-Generation-Time Settings
One related setting is applied only when the OpenAPI specification is generated, not at runtime.
String fields without a validation regex
This setting controls whether a pattern is automatically added to string fields in the generated OpenAPI spec if they do not already have one from the source XSD or an operator override.
length-bound (default): Applies a pattern of ^[\s\S]{min,max}$ based on the field's length limits. This does not change runtime validation behavior.
alphanumeric-length: Applies ^[0-9a-zA-Z]{min,max}$. This is stricter and will cause validation failures for spaces, punctuation, or non-Latin text if validation is in enforce mode.
generic: Applies a user-defined generic regex template to all applicable fields.
This setting applies to request string fields that lack an XSD pattern, an enumeration, or an operator-defined regex. Fields with no maxLength or a maxLength over 1000 receive an unbounded pattern. Response fields are not affected.
Applying Spec-Generation Changes
After changing a spec-generation setting, you must regenerate existing API specifications for the change to take effect.
POST /admin/v1/openapi:regenerate-all
Troubleshooting
Backend failures are returned as HTTP 200 OK
Condition: An API consumer receives an HTTP 200 OK response, but the body contains a SOAP Fault or error structure.
Cause: The Upstream failure status option is set to mask-as-200.
Resolution: Set the option to propagate (the default) to ensure backend failures are mapped to appropriate 4xx/5xx HTTP status codes.
Missing required fields do not cause an error
Condition: A response from the backend is missing a field marked as required in the schema, but the gateway forwards the response to the consumer without an error.
Cause: The Required handling option is set to permissive (the default).
Resolution: To enforce this constraint, set the option to fail-with-502. The gateway will then return an HTTP 502 error for such responses.
Internal backend details appear in error responses
Condition: API consumers report seeing stack traces, internal hostnames, or other sensitive information in error responses.
Cause: The SOAP fault-detail exposure option is set to full.
Resolution: Change this security-sensitive setting to safe (the default). This will strip backend-specific details from the client-facing error payload.
