Conversion options reference

SOAP and REST disagree on a lot of small things: how a date should look, whether a single-element list is an array, whether an absent value is null or omitted, how a field should be named, what an error body looks like. Each of those decisions is a conversion option you control — with a sensible default out of the box. This page is the operator reference for every option, its modes, and the resolution hierarchy.

Options are set under Settings → Conversion defaults (platform-wide) and overridden per service / operation / field where the UI exposes that tier. The generated OpenAPI v3 contract reflects your choices, so the documentation always matches the runtime behavior.

---

The resolution hierarchy

Every option resolves through a fixed precedence chain — the most specific setting wins:

System default  →  per-Service  →  per-Operation  →  per-Field  →  (hardcoded fallback)
   (broadest)                                              (most specific)

Two important facts about the tiers — they are not uniform across options:

• Per-Operation is the real "per-service-ish" tier for most options. Of the runtime conversion options, only the two validation-mode options (request-validation and response-validation) have a genuine per-Service override. For every other option, the middle override tier is per-Operation — set the option once at the system level and override it on the specific operations that need it. The Settings UI labels these cards "per-Operation" accordingly.
• Body-level options have no per-Field tier. Options that act on the whole response body rather than an individual leaf — response envelope wrap, error/fault shape, JSON field ordering, and SOAP header propagation — are tunable at system and operation level but not per-field. There is no single field to attach them to.

Per-field overrides are authored in the mapping UI; see Field-level overrides.

---

Option catalog

The runtime exposes the options below. Defaults shown are the platform (system) defaults.

Date / time

| | | |---|---| | What it controls | How xsd:date / xsd:dateTime values render in JSON. | | Modes (format) | iso-8601-utc (default) · iso-8601-utc-strict · iso-8601-local · iso-8601-offset · epoch-millis · epoch-seconds · custom | | Companion sub-fields | Custom pattern (when format = custom) · Timezone (utc / local / passthrough, default utc) · Local timezone (an IANA zone-id such as Asia/Jerusalem, only when timezone = local) | | Tiers | System → Operation → Field. |

The per-field date/time override exposes all four sub-fields (format, custom pattern, timezone, local timezone) on one chip.

Numeric handling

| | | |---|---| | What it controls | How numbers render, including large integers that exceed safe JSON precision. | | Modes | as-number (default) · as-string · as-string-when-unsafe (numbers render as numbers unless they exceed JSON-safe integer precision, in which case they render as strings) | | Tiers | System → Operation → Field. |

Boolean handling

| | | |---|---| | What it controls | How boolean values are represented. | | Modes | as-bool (default — JSON true/false) · as-int (1/0) | | Tiers | System → Operation → Field. | | Direction model | Bidirectional — request and response sides carry separate per-field overrides, both consulted at runtime. |

Null / empty handling

| | | |---|---| | What it controls | What an absent, xsi:nil, or empty value becomes in JSON. | | Modes | as-null · as-empty-value · omit-field | | Defaults | Request side: omit-field. Response side: as-null. | | Tiers | System → Operation → Field. | | Direction model | Bidirectional — separate request and response columns/chips. |

Array collapse

| | | |---|---| | What it controls | How a single-element list is represented. | | Modes | always-array (default — a one-element list is still a JSON array) · collapse-when-single (a one-element list collapses to a scalar) | | Tiers | System → Operation → Field. (Response side.) |

Whitespace handling

| | | |---|---| | What it controls | Text trimming / normalization. | | Modes | preserve (default) · trim · collapse (collapse internal runs) · trim-ascii-only · collapse-ascii-only | | Tiers | System → Operation → Field. (Response side.) |

The two *-ascii-only modes are opt-in variants that only normalize ASCII whitespace, leaving non-ASCII whitespace (relevant to some non-Latin scripts) untouched.

Binary encoding

| | | |---|---| | What it controls | How xsd:base64Binary / xsd:hexBinary members render. | | Modes | passthrough (default) · base64 · hex · data-url | | Companion sub-field | Data-URL MIME type (when mode = data-url) | | Tiers | System → Operation → Field. (Response side.) |

Duration

| | | |---|---| | What it controls | How xsd:duration renders. | | Modes | passthrough (default — ISO-8601 duration string) · seconds (total seconds) · components (a {days, hours, minutes, seconds} object) | | Tiers | System → Operation → Field. (Response side.) |

Required handling

| | | |---|---| | What it controls | What happens when a required field arrives empty. | | Modes | permissive (default) · fail-with-502 | | Tiers | System → Operation → Field. (Response side.) |

Field-name casing

| | | |---|---| | What it controls | The naming style of JSON field names. | | Modes | as-source (default) · camelCase · snake_case · kebab-case · PascalCase | | Tiers | System → Operation → Field. (Response side.) |

xsi:type discriminator

| | | |---|---| | What it controls | How a polymorphic xsi:type is represented in JSON. | | Modes | strip (default — drop the type hint) · keep-as-meta (keep it as metadata) · discriminator-field (emit it as a named discriminator field) | | Companion sub-field | Discriminator field name (when mode = discriminator-field) | | Tiers | System → Operation → Field. (Response side.) |

Response envelope wrap (body-level)

| | | |---|---| | What it controls | The shape of the REST response body. | | Modes | raw (default — the payload directly) · data-key-only (payload under a data key) · wrapped-with-meta (payload plus a metadata block) | | Tiers | System → Operation. (Body-level — no per-field tier.) |

Error / fault shape (body-level)

| | | |---|---| | What it controls | The JSON shape of a non-2xx / fault response. | | Modes | s2r-default (default) · rfc7807 (RFC 7807 Problem Details) · flat · upstream-passthrough (the backend's error payload, unchanged) | | Tiers | System → Operation. (Body-level — no per-field tier.) |

JSON field ordering (body-level)

| | | |---|---| | What it controls | Key order in the response JSON. | | Modes | as-schema (default — XSD declared order) · alphabetical · preserve-source (the order the backend returned) | | Tiers | System → Operation. (Body-level — no per-field tier.) |

SOAP header propagation (body-level)

| | | |---|---| | What it controls | What happens to inbound <soap:Header> content. | | Modes | drop (default — with a Security denylist) · expose-as-meta (in response metadata) · expose-as-http-headers | | Tiers | System → Operation. (Body-level — no per-field tier.) |

Upstream failure status

| | | |---|---| | What it controls | The HTTP status a backend failure surfaces as. | | Modes | propagate (default — map the fault to a 4xx/5xx) · mask-as-200 (return HTTP 200 with the fault in the body) | | Tiers | System → Operation. (No per-field tier — it's a response-status decision.) |

In the generated OpenAPI v3 this surfaces as extension keys (x-s2r-upstream-failure-status, x-s2r-failure-body-in-200).

Request validation mode

| | | |---|---| | What it controls | Enforcement of the inbound request contract. | | Modes | off · shadow (default — log would-be failures, do not reject) · enforce (reject non-conforming requests) | | Tiers | System → Service. (One of only two options with a real per-service tier.) |

Response validation mode

| | | |---|---| | What it controls | Contract checking of the backend response. | | Modes | off · monitor (default — log would-be failures, do not reject) · enforce (reject non-conforming responses) | | Tiers | System → Service. (One of only two options with a real per-service tier.) |

See Validation modes for how shadow/monitor lets you preview enforcement before you turn it on, and the per-field validation regexes that ride on top of these modes.

Integer range bounds (spec-emission only)

| | | |---|---| | What it controls | Whether the generated OpenAPI spec stamps the synthetic natural int32/int64 minimum/maximum bounds on integer fields. | | Modes | emit (default) · omit | | Tiers | System → Operation → Field. | | Note | Documentation-only. This affects the generated OpenAPI spec, not the runtime payload conversion. |

---

Onboarding-time setting (not a runtime knob)

One related setting is applied at onboarding time rather than per request:

• String fields without a validation regex — notify-only (default) · notify-and-suggest · auto-apply-silent · none, with an associated generic-regex template. This governs how the platform treats string fields that arrive with no XSD pattern, during mapping generation. It is not resolved per call at runtime.

---

How options reach the contract and the runtime

Each option is applied in two places, kept aligned:

• At runtime — the runtime resolves the effective mode for a call through the hierarchy above and applies it during conversion.
• In the generated OpenAPI v3 — the spec generator resolves the same effective mode and emits the corresponding schema (or extension key) so the published contract matches the runtime. Editing an option therefore changes both the behavior and the documentation.

---

Next reads

• How mapping works — the deterministic full-field model these options ride on.
• Field-level overrides — authoring per-field option overrides in the UI.
• Validation modes — the request/response validation options in depth.
• SOAP & XSD support — the type coverage these options operate on.

---

All Specaria SOAP to REST docs