Field-Level Overrides

Overview

Field-level overrides provide a mechanism to configure conversion behavior for a specific field within a single API operation. While the default mapping is deterministic and handles most fields automatically, overrides are used for exceptions where a single field must behave differently from the system, service, or operation-level settings.

Overrides are the most specific tier in the conversion option hierarchy, allowing for fine-grained control without altering the broader conversion logic. They are configured through the platform's user interface, not by writing mediation scripts.

The Conversion Option Hierarchy

Settings are resolved from the most general to the most specific. A field-level override takes precedence over any conflicting setting at a higher level.

flowchart LR
    A[System Default] --> B[Per-Service Setting]
    B --> C[Per-Operation Setting]
    C --> D(Per-Field Override)
    style D fill:#f9f,stroke:#333,stroke-width:2px

How It Works

A field-level override modifies two aspects of the API:

1. Runtime Conversion: It changes how the data for that specific field is transformed between the SOAP backend and the REST client at runtime.
2. Generated OpenAPI Specification: It updates the corresponding field's definition in the generated OpenAPI v3 schema to match the runtime behavior.

This ensures that the published API contract accurately reflects the conversion logic. For example:

• Changing Field-name casing to snake_case renames the JSON property in the OpenAPI schema.
• Adding a Validation regex emits a pattern constraint for that property.
• Setting Integer range bounds adds or removes minimum and maximum validation keywords in the schema.

Authoring a Field-Level Override

API publishers can add or modify field overrides by following these steps in the UI:

1. Navigate to Services, select the target service, and open the Mapping tab.
2. Select the operation you wish to modify. The request and response contract trees will be displayed.
3. Locate the specific leaf field in the tree that requires an override.
4. Open the field's override chip and configure the desired conversion option (e.g., change a date format to epoch-millis).
5. Save the mapping. This action creates a new mapping revision.
6. Use the SOAP application test or REST test to verify that the override behaves as expected before activating the new revision.

Available Field-Level Overrides

Overrides are available for leaf-level conversion options. The following settings can be configured on a per-field basis:

• Date / time: Includes format, custom pattern, timezone, and local timezone settings.
• Numeric handling
• Boolean handling
• Null / empty handling
• Array collapse
• Whitespace handling
• Binary encoding: Includes the data-URL MIME type.
• Duration
• Required handling
• Field-name casing
• xsi:type discriminator: Includes the discriminator field name.
• Integer range bounds: Affects only the generated OpenAPI specification.
• Validation regexes: A per-field regular expression pattern that is enforced based on the active validation mode.

Options Not Available at the Field Level

Body-level options affect the entire request or response payload and therefore cannot be attached to a single field. These options must be configured at the system or operation level:

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

For details on which tiers each option can be configured at, see the conversion options reference.

Direction-Aware Overrides

While most field-level overrides apply a single setting for response-side conversion, some options are bidirectional, allowing for separate configurations for requests and responses.

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 override values at runtime. If you need to apply a directional split to an option that is not natively bidirectional at the field level, you must configure it at the operation tier instead.

Verification and Rollback

Because every change to a mapping creates a new, immutable revision, you can manage changes safely.

• Verification: Always use the built-in test tools to confirm that a new mapping revision with field overrides behaves correctly before activating it for consumer traffic.
• Rollback: If a new revision introduces an issue, you can revert to a previous, known-good mapping version. For more details, see Publish & version a service.

See Also

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

All SOAP-to-REST docs