Conversion Options Reference

Overview

When translating SOAP services to REST, there are numerous small but significant differences in data representation conventions. SOAP and REST disagree on formats for dates, the representation of single-element lists, the handling of absent values, field naming conventions, and error body structures.

This platform provides a set of conversion options to give API publishers precise control over these transformations. Each option comes with a sensible default, but can be overridden to match the specific requirements of API consumers.

Options can be configured globally under Settings → Conversion defaults, and then overridden for specific services, operations, or even individual fields where the user interface provides that level of granularity. The generated OpenAPI v3 contract automatically reflects the configured options, ensuring that the API documentation always matches the runtime behavior.

How it Works

Resolution Hierarchy

Every conversion option is resolved through a fixed precedence chain, where the most specific setting always wins. The platform evaluates the tiers in the following order:

flowchart TD
    subgraph "Resolution Precedence"
        direction LR
        A["System Default (Broadest)"] --> B["Per-Service"] --> C["Per-Operation"] --> D["Per-Field (Most Specific)"] --> E["Hardcoded Fallback"]
    end

There are two important characteristics of this hierarchy:

• Per-Operation is the primary override tier for most options. Of all the runtime conversion options, only request-validation and response-validation can be set at the per-Service level. For all other options, overrides are applied at the per-Operation level.
• Body-level options lack a per-Field tier. Options that affect the entire request or response body—such as response envelope wrap, error/fault shape, JSON field ordering, and SOAP header propagation—can be configured at the system and operation levels, but not for individual fields.

Per-field overrides are configured in the mapping UI. For more details, see the documentation on field-level overrides.

Contract and Runtime Alignment

Each conversion option is applied in two places to ensure consistency:

• At runtime: The conversion engine resolves the effective mode for each API call using the resolution hierarchy and applies the corresponding transformation.
• In the generated OpenAPI v3 specification: The spec generator resolves the same effective mode and emits the corresponding schema definition or extension key. This ensures the published contract accurately reflects the runtime behavior. As a result, editing an option changes both the behavior of the API and its documentation simultaneously.

Conversion Options Reference

The following sections detail every runtime conversion option available. Defaults shown are the system-level platform defaults.

Date / time

Controls how xsd:date and xsd:dateTime values are rendered in JSON.

• Tiers: System → Operation → Field
• Modes:
  • iso-8601-utc (default)
  • iso-8601-utc-strict
  • iso-8601-local
  • iso-8601-offset
  • epoch-millis
  • epoch-seconds
  • custom
• Companion Sub-fields:
  • Custom pattern: A string defining the format, used when format is custom.
  • Timezone: utc (default), local, or passthrough.
  • Local timezone: An IANA time zone identifier (e.g., Asia/Jerusalem), used when Timezone is local.
  • Nil value representation: omit (default) or null. This controls how an empty or absent date/time value is represented. omit removes the key from the JSON object, while null includes the key with a JSON null value. This setting is specific to date/time types and influences the OpenAPI spec (nullable: true is set for null).

Numeric handling

Controls how numbers are rendered, particularly large integers that may exceed safe precision limits in JSON.

• Tiers: System → Operation → Field
• Modes:
  • as-number (default): Renders all numbers as JSON numbers.
  • as-string: Renders all numbers as JSON strings.
  • as-string-when-unsafe: Renders numbers as JSON numbers, unless they exceed JSON-safe integer precision, in which case they are rendered as strings.

Boolean handling

Controls how boolean values are represented in JSON.

• Tiers: System → Operation → Field
• Direction Model: Bidirectional. Separate overrides can be configured for the request and response.
• Modes:
  • as-bool (default): Renders as JSON true or false.
  • as-int: Renders as 1 or 0.

Null / empty handling

Controls what an absent, xsi:nil, or empty value from the SOAP payload becomes in the JSON body.

• Tiers: System → Operation → Field
• Direction Model: Bidirectional. Separate settings are available for the request and response.
• Defaults:
  • Request side: omit-field
  • Response side: as-null
• Modes:
  • as-null
  • as-empty-value
  • omit-field

Array collapse

Controls how lists containing a single element are represented in JSON. This option applies to the response side only.

• Tiers: System → Operation → Field
• Modes:
  • always-array (default): A single-element list is rendered as a JSON array.
  • collapse-when-single: A single-element list is rendered as a scalar value.

Whitespace handling

Controls text trimming and normalization for string values. This option applies to the response side only.

• Tiers: System → Operation → Field
• Modes:
  • preserve (default): Retains all original whitespace.
  • trim: Removes leading and trailing whitespace.
  • collapse: Collapses internal runs of whitespace into a single space.
  • trim-ascii-only: A variant of trim that only affects ASCII whitespace.
  • collapse-ascii-only: A variant of collapse that only affects ASCII whitespace.

Binary encoding

Controls how xsd:base64Binary and xsd:hexBinary members are rendered. This option applies to the response side only.

• Tiers: System → Operation → Field
• Modes:
  • passthrough (default)
  • base64
  • hex
  • data-url
• Companion Sub-field:
  • Data-URL MIME type: A string specifying the MIME type, used when mode is data-url.

Duration

Controls how xsd:duration values are rendered. This option applies to the response side only.

• Tiers: System → Operation → Field
• Modes:
  • passthrough (default): Renders as an ISO-8601 duration string.
  • seconds: Renders as the total number of seconds.
  • components: Renders as a JSON object with keys {days, hours, minutes, seconds}.

Required handling

Controls behavior when a required field is empty in the backend response. This option applies to the response side only.

• Tiers: System → Operation → Field
• Modes:
  • permissive (default): Allows the empty value.
  • fail-with-502: Causes the gateway to return a 502 Bad Gateway error.

Field-name casing

Controls the naming convention of JSON field names. This option applies to the response side only.

• Tiers: System → Operation → Field
• Modes:
  • as-source (default): Uses the name from the source WSDL/XSD.
  • camelCase
  • snake_case
  • kebab-case
  • PascalCase

xsi:type discriminator

Controls how a polymorphic xsi:type attribute from the SOAP payload is represented in JSON. This option applies to the response side only.

• Tiers: System → Operation → Field
• Modes:
  • strip (default): Drops the type hint.
  • keep-as-meta: Retains the type hint as metadata.
  • discriminator-field: Emits the type hint as a named discriminator field in the JSON object.
• Companion Sub-field:
  • Discriminator field name: A string specifying the field name, used when mode is discriminator-field.

Response envelope wrap (body-level)

Controls the overall structure of the REST response body.

• Tiers: System → Operation
• Modes:
  • raw (default): The response body is the payload directly.
  • data-key-only: The payload is nested under a data key.
  • wrapped-with-meta: The response body contains the payload along with a metadata block.

Error / fault shape (body-level)

Controls the JSON structure of a non-2xx or SOAP Fault response.

• Tiers: System → Operation
• Modes:
  • 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 error object.
  • upstream-passthrough: The backend's error payload is passed through unchanged.

JSON field ordering (body-level)

Controls the order of keys in the response JSON object.

• Tiers: System → Operation
• Modes:
  • as-schema (default): Orders keys according to their declaration order in the source XSD.
  • alphabetical: Orders keys alphabetically.
  • preserve-source: Preserves the key order returned by the backend service.

SOAP header propagation (body-level)

Controls how inbound <soap:Header> content is handled.

• Tiers: System → Operation
• Modes:
  • drop (default): Discards SOAP headers. A denylist is applied to Security headers.
  • expose-as-meta: Includes header content in the response metadata.
  • expose-as-http-headers: Maps SOAP headers to HTTP response headers.

SOAP fault-detail exposure (body-level, security)

Controls how much detail from a backend <soap:Fault> is exposed to the API consumer. This is a security-sensitive setting.

• Tiers: System → Operation
• Modes:
  • safe (default): Strips backend-identifying and free-text fields (faultActor, faultNode, faultRole, detail) that may contain sensitive information like stack traces or internal hostnames. Only client-safe fields (faultCode, faultString, faultSubcode, reasons) are exposed.
  • full: Passes the entire <soap:Fault> content through verbatim. This requires an explicit operator opt-in.

Outbound MTOM / XOP request (transport)

Controls whether the request to the backend SOAP service is sent with attachments inline or using MTOM (Message Transmission Optimization Mechanism).

• Tiers: System default only.
• Modes:
  • off (default): Sends the request as a standard text/xml or application/soap+xml payload.
  • on: Sends the request as multipart/related with xop:Include elements, for backends that require MTOM.

Upstream failure status

Controls the HTTP status code returned to the client when the backend service fails.

• Tiers: System → Operation
• Modes:
  • propagate (default): Maps the backend fault to an appropriate 4xx or 5xx HTTP status code.
  • mask-as-200: Returns an HTTP 200 OK status, with the fault details included in the response body.

Request validation mode

Controls the enforcement of the inbound request contract.

• Tiers: System → Service
• Modes:
  • off: No validation is performed.
  • shadow (default): Logs requests that would fail validation but does not reject them.
  • enforce: Rejects requests that do not conform to the contract.

Response validation mode

Controls contract checking of the response from the backend service.

• Tiers: System → Service
• Modes:
  • off: No validation is performed.
  • monitor (default): Logs responses that would fail validation but does not reject them.
  • enforce: Rejects non-conforming responses from the backend, typically resulting in a 502 error to the client.

Integer range bounds (spec-emission only)

Controls whether the generated OpenAPI specification includes synthetic minimum and maximum bounds for int32 and int64 fields.

• Tiers: System → Operation → Field
• Modes:
  • emit (default): Adds minimum and maximum to integer fields in the OpenAPI spec.
  • omit: Does not add these bounds to the spec.

Onboarding-Time Settings

One related setting is applied during the initial service onboarding and mapping generation, not as a runtime conversion option.

• String fields without a validation regex: This setting governs how the platform handles string fields that lack a pattern facet in the source XSD. It is not resolved per-call at runtime.
  • Modes: notify-only (default), notify-and-suggest, auto-apply-silent, none.
  • Companion Sub-field: An associated generic-regex template.

See Also

• How mapping works: Learn about the deterministic field model that these conversion options build upon.
• Field-level overrides: See how to author per-field option overrides in the UI.
• Validation modes: Explore the request and response validation options in greater depth.
• SOAP and XSD type support: Review the type coverage that these options operate on.

All SOAP-to-REST docs