Validation Modes for Request and Response Contracts

Overview

Validation is a mechanism for checking that inbound requests and outbound backend responses conform to their respective API contracts. It provides a way to enforce contract compliance and, critically, to preview the impact of enforcement on live traffic before it is enabled. This de-risks the rollout of contract-based validation by allowing API publishers to see what traffic would be rejected without actually blocking it.

There are two independent validation options:

• Request validation: Checks the inbound request from an API consumer against the request contract.
• Response validation: Checks the response from the backend service against the response contract.

Both are configured as conversion options and can be set as a system-wide default, with the ability to override the setting on a per-service basis.

How it works

For both request and response validation, the platform evaluates traffic against the contract according to one of three modes. The non-enforcing modes (shadow and monitor) are designed to provide a data-driven preview of what the enforce mode would do.

In these preview modes, the platform evaluates the contract for every call and records any would-be failures in observability logs. However, the traffic flow is not altered or rejected. This allows API publishers to analyze real traffic patterns, identify non-conforming calls, and fix the underlying issues—whether in the calling application, the contract itself, or through a field override—before activating enforcement.

Once the stream of would-be failures is clean, the service can be switched to enforce mode. In this mode, non-conforming traffic is actively rejected with a coded error, protecting the backend from invalid requests and protecting the consumer from invalid responses.

Validation Modes

Request and response validation can each be configured with one of three modes. While the names for the log-only mode differ, their function is identical: evaluate and log, but do not reject.

	Request validation	Response validation
Off	off	off
Log-only (preview)	shadow (default)	monitor (default)
Enforce	enforce	enforce

Off

When set to off, no validation is performed for the corresponding request or response. The conversion process proceeds on a best-effort basis.

Shadow (request) / Monitor (response)

This is the default mode for both request and response validation. In this mode, the platform performs validation checks and logs any detected contract violations as "would-be failures." However, it does not block or modify the traffic. This allows you to gather data on non-conforming traffic without impacting consumers or backend services. The would-be failures are surfaced in the observability system for analysis.

Enforce

When validation is set to enforce, any traffic that does not conform to the contract is rejected.

• Request enforce: A non-conforming inbound request is rejected before it is sent to the backend service. The API consumer receives a clear, coded error.
• Response enforce: A non-conforming response from the backend service is intercepted and not passed to the API consumer. Instead, the consumer receives a coded error indicating a contract violation by the backend.

Recommended Rollout Process

The validation modes are designed to support a gradual and safe rollout of contract enforcement. The recommended process is as follows:

off / (default shadow|monitor)  →  inspect would-be failures  →  fix  →  enforce

1. Start in shadow / monitor mode. This is the default, so for a new service, you can simply let representative traffic flow.
2. Review would-be failures. Use the observability tools to inspect the logged validation failures. Identify the root cause: are they genuine contract violations from a client, incorrect data from a backend, or perhaps a stale contract that needs updating?
3. Resolve the issues. Based on your analysis, take corrective action. This may involve working with API consumers to fix their requests, adjusting backend services to produce compliant responses, updating the contract, or applying a field-level override.
4. Switch to enforce mode. Once the stream of would-be failures is clean and you are confident that legitimate traffic will not be blocked, update the service's configuration to enforce.

Configuration is managed at two levels:

• Platform-wide: Set under Settings → Conversion defaults.
• Per-service: Set under Services → your service. This override allows different services to progress toward enforcement at their own pace.

Per-Field Validation with Regex

In addition to the overall validation mode, you can apply more granular constraints using per-field validation regular expressions.

A pattern constraint can be attached to a leaf field as a field-level override. These patterns are direction-aware, meaning you can define separate regexes for request and response validation. The regex engine is UTF-8 and Hebrew-aware.

The behavior of a regex mismatch depends on the active validation mode:

• In shadow / monitor mode, a mismatch is logged as a would-be failure.
• In enforce mode, a mismatch causes the request or response to be rejected.

Regardless of the mode, the pattern is automatically included in the generated OpenAPI v3 schema for the service, making the constraint part of the published contract.

This feature is related to the onboarding-time setting for "string fields without a validation regex", which controls how the platform handles string fields that lack an XSD pattern during initial mapping generation. For more details, see the conversion options reference.

Troubleshooting

The primary tool for troubleshooting validation issues is the shadow and monitor preview mode. By enabling this mode (which is on by default), you can collect data on all potential contract violations without impacting service availability.

• Would-Be Failures: When validation is in shadow or monitor mode, any non-conforming request or response generates a log entry in the observability system. These logs allow you to identify which fields are failing validation, for which operations, and why.
• Enforcement Rejections: When validation is in enforce mode, non-conforming traffic is rejected with a "clear, coded error". This signals a contract violation to the caller (for request validation) or logs an error and signals a failure to the consumer (for response validation).

Common reasons for validation failures include genuine contract violations by a client, stale examples in test suites, or fields that require a specific field-level override to align with real-world data.

See Also

• Conversion Options Reference
• Field-Level Overrides
• Observability (where would-be failures are surfaced)

---

All SOAP-to-REST docs