Field-Level Conversion Overrides

Overview

Field-level overrides provide a mechanism for fine-grained control over the data conversion process. While the default mapping generation is deterministic and handles most fields automatically, overrides are used for exceptional cases where a single field within a single operation must behave differently from the default.

These overrides are configured directly in the user interface, eliminating the need for manual mediation scripts. They represent the most specific tier in the conversion option hierarchy, allowing an API publisher to modify behavior for a single leaf field without affecting other fields, operations, or services.

An override changes both the runtime conversion behavior for the specified field and the corresponding generated OpenAPI v3 schema, ensuring that the published contract accurately reflects the runtime execution.

The Conversion Option Hierarchy

Field-level overrides are the final and most specific step in the settings resolution process. The system applies the first setting it finds, starting from the most specific level (Field) and moving to the most general (System default).

System default  →  per-Service  →  per-Operation  →  per-Field
                                                       ↑ overrides here

Options that are not set at the field level will inherit their values from the operation, service, or system default tiers.

How Overrides Work

Field-level overrides are managed via chips displayed next to leaf fields in an operation's request and response mapping trees in the UI. Each chip corresponds to a category of conversion options.

Scope of Effect

A field override affects two distinct outputs:

1. Runtime Conversion: The override directly alters how data for that specific field is transformed between the SOAP and REST formats during a live API call.
2. Generated OpenAPI v3 Schema: The override updates the generated OpenAPI specification to match the runtime behavior. For example:
   • A Field-name casing override changes the JSON property name in the schema.
   • A Validation regex override adds a pattern constraint to the schema property.
   • An Integer range bounds override adds or removes minimum and maximum constraints.

This dual effect ensures that the published API contract remains consistent with the service's actual behavior.

Request vs. Response Directionality

Most field-level options apply a single setting to the response-side conversion. However, some options are bidirectional, allowing for separate configurations for the request and response paths.

The following options are direction-aware at the field level:

• Boolean handling
• Null / empty handling
• Validation regexes

For these options, the system consults both the request-side and response-side overrides at runtime. If you need to apply direction-specific logic to an option that is not natively bidirectional at the field level, you must configure it at the operation tier instead.

Configurable Field-Level Options

The following conversion options can be configured on a per-field basis.

• Array collapse: Controls the handling of arrays.
• Binary encoding: Sets the encoding for binary data and the data-URL MIME type.
• Boolean handling: Defines the representation of boolean values. (Bidirectional)
• Date / time: A single chip controls format, custom pattern, timezone, and local timezone settings.
• Duration: Manages the format of duration values.
• Field-name casing: Modifies the casing of the field name (e.g., snake_case).
• Integer range bounds: Emits minimum/maximum values in the OpenAPI specification. This affects OpenAPI generation only.
• Null / empty handling: Governs the conversion of null or empty values. (Bidirectional)
• Numeric handling: Controls the processing of numeric types.
• Required handling: Manages whether a field is treated as required.
• Validation regexes: A per-field regular expression pattern enforced by the active validation mode. Emitted as a pattern in the OpenAPI schema. (Bidirectional)
• Whitespace handling: Defines how whitespace characters are managed.
• xsi:type discriminator: Controls the handling of xsi:type attributes and the name of the discriminator field.

Options Not Configurable Per Field

Body-level options act on the entire request or response payload and cannot be attached to a single leaf field. These must be configured at the system, service, or operation level.

• Response envelope wrap
• Error / fault shape
• JSON field ordering
• SOAP header propagation
• Upstream failure status
• Request / response validation mode (set per service)

Refer to the conversion options reference for a complete list of options and their available configuration tiers.

How to Author a Field-Level Override

Follow these steps to configure an override for a specific field:

1. Navigate to Services, select your service, and open the Mapping tab.
2. Select the operation you wish to modify. The request and response contract trees will be displayed with the auto-generated mapping.
3. Locate the leaf field you need to change in either the request or response tree.
4. Click the override chip for that field and configure the desired option. For example, you might change a date field's format to epoch-millis or a string field's casing to snake_case.
5. Click Save. This action creates a new, immutable revision of the mapping; the currently active version is not modified in place.
6. Before activating the new revision, verify its behavior using the SOAP application test or REST test. These tests use the exact same runtime conversion path that will be used in production.

Because each change creates a new mapping revision, you can always roll back to a previous known-good version if a change introduces unintended behavior.

See Also

• Conversion Options Reference
• Validation Modes
• Generate & Review the OpenAPI
• Publish & Version a Service

---

All SOAP-to-REST docs