Request and Response Validation Modes

Overview

Validation is the process of checking API traffic against its governing contract. The platform provides independent validation for both inbound requests and backend responses. This feature solves the critical problem of enforcing contract compliance without disrupting live traffic during rollout.

The primary mechanism for this is a "preview" mode that evaluates the contract for every call and logs any would-be failures without rejecting the traffic. This allows an API publisher to gather data on non-conforming traffic, fix the underlying issues in the data or the contract, and then confidently enable enforcement.

Validation is configured as a conversion option, with settings that can be applied globally as a system default and overridden on a per-service basis.

How It Works

The platform provides two distinct validation streams that can be configured independently:

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

Each stream can be set to one of three modes: off, a preview mode (shadow or monitor), or enforce.

The data flow changes based on the configured mode. In enforce mode, validation acts as a gate, rejecting non-compliant traffic before it proceeds.

flowchart TD
    subgraph Request Validation
        A[API Consumer Request] --> B{Validate Request?};
        B -- enforce --> C{Is valid?};
        C -- No --> D[Reject with Coded Error];
        C -- Yes --> E[Call Backend Service];
        B -- shadow/off --> E;
    end

    subgraph Response Validation
        F[Backend Service Response] --> G{Validate Response?};
        G -- enforce --> H{Is valid?};
        H -- No --> I[Return Coded Error to Consumer];
        H -- Yes --> J[Return Response to Consumer];
        G -- monitor/off --> J;
    end

    E --> F;

Validation Modes

The platform supports three operational modes for both request and response validation.

• off: No validation is performed. The conversion process proceeds on a best-effort basis. This mode carries the risk of passing non-compliant data.

• shadow (for requests) / monitor (for responses): This is the default preview mode. The platform evaluates the contract on every call and records any validation failures. However, it does not reject or alter the traffic. These "would-be failures" are surfaced in the platform's observability tools, allowing you to analyze the impact of enforcement before enabling it.

• enforce: The platform actively enforces the contract.

  • When enforce is set for request validation, an inbound request that fails validation is immediately rejected with a coded error. The request never reaches the backend service.
  • When enforce is set for response validation, a backend response that fails validation is intercepted. Instead of passing the non-compliant payload to the API consumer, the platform returns a coded error.

Configuration

Validation modes can be configured globally and then overridden for each specific service, allowing different services to progress toward enforcement at their own pace.

• Platform-wide default: Set under Settings → Conversion defaults.
• Per-service override: Set under Services → your service.

The available modes are detailed below.

Recommended Rollout Procedure

To de-risk the process of enabling enforcement, follow this data-driven rollout sequence.

flowchart LR
    A(Start in<br>shadow/monitor) --> B(Inspect<br>would-be failures);
    B --> C(Resolve issues);
    C --> D(Switch to<br>enforce);

1. Start in shadow / monitor mode. This is the default, so you may already have data. Allow a representative volume of traffic to flow through the service.
2. Review would-be failures. Use the platform's observability tools to find and analyze logged validation failures. Identify the root cause: genuine contract violations, outdated examples in test suites, or fields that require a specific override.
3. Resolve the issues. This may involve correcting the data source, adjusting a field override, or updating the contract to relax a constraint.
4. Switch to enforce mode. Once the stream of would-be failures is clean and you are confident that legitimate traffic will not be rejected, update the service's configuration to enforce.

Per-Field Regex Validation

In addition to schema-level validation, the platform supports per-field validation using regular expressions.

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

The behavior of a regex mismatch is governed by the broader 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.

Any configured pattern is automatically included in the generated OpenAPI v3 schema, ensuring the constraint is documented for API consumers.

Troubleshooting

When traffic does not conform to the contract, the platform provides clear signals depending on the validation mode.

• Would-Be Failures:

  • When: Occur in shadow (request) or monitor (response) mode.
  • What it means: A request or response did not match the contract. The traffic was still processed and passed through, but the mismatch was logged.
  • Action: Investigate these logs in observability to understand what traffic would be rejected under enforce mode.

• Rejection with a Coded Error:

  • When: Occurs in enforce mode.
  • What it means: A non-conforming request or response was received and actively rejected.
    • For a request, the API consumer receives an error, and the call never reaches your backend.
    • For a response, the backend's non-compliant response is blocked, and the API consumer receives an error instead of a malformed payload.
  • Action: The error indicates a contract violation that must be fixed by either the API consumer (for requests) or the backend service owner (for responses).

See Also

• Conversion options reference
• Field-level overrides
• Observability

All SOAP-to-REST docs