WSDL Contract Round-Trip Validator

Overview

The WsdlContractRoundTripValidator is a service component that runs during the WSDL import process. Its purpose is to prevent a class of runtime errors where a contract, after being transformed and stored during import, becomes inconsistent with the platform's runtime validation logic.

This validator solves the "round-trip" problem: ensuring that data conforming to the contract as understood by an API consumer would also be accepted by the backend runtime validator after any import-time transformations. It was created to address a historical issue where a change in how regular expression patterns were stored caused valid production traffic to be rejected.

The validator is invoked by the import process after a service version's request and response contracts are generated from a WSDL by the WsdlContractBuilder, but before the import is finalized. It inspects every scalar field in the contract, validating the field's auto-generated example value against its own stored constraints. If any example fails its own validation, a warning is generated, allowing the API publisher to correct the issue before it affects production traffic.

How it works

The round-trip validation process is designed to be a non-blocking check on the API onboarding path. It simulates how the runtime would validate data for the contract that is about to be saved.

flowchart TD
    subgraph WSDL Import Process
        A[Start Import] --> B[Generate Contract from WSDL];
        B --> C[Run Round-Trip Validation];
    end

    subgraph Round-Trip Validation Logic
        C --> D{For each operation};
        D --> E[Process Request & Response Schemas];
        E --> F[Get flat list of all scalar fields with examples];
        F --> G{For each scalar field};
        G --> H[Validate field's example against its own constraints];
        H --> I{Is example valid?};
        I -- No --> J[Add to violation list];
        I -- Yes --> G;
        J --> G;
    end

    C --> K{Any violations found?};
    K -- Yes --> L[Report violations as a Warning];
    K -- No --> M[Finalize Import];
    L --> M;

The validation flow proceeds as follows:

1. The validator receives a list of WsdlOperationRecord objects, each representing an operation from the imported WSDL.
2. For each operation, it iterates through its request and response contract schemas.
3. It calls the ContractExampleService.describeContractFields method to produce a flattened list of all scalar fields within the schema. Each entry in this list contains the field's constraints (such as pattern, minLength, maxLength) and a generated exampleValue.
4. For each scalar field that has an exampleValue, the validator calls SoapMessageMapper.wouldAcceptScalar. This method contains the same validation logic used by the runtime to check incoming requests.
5. wouldAcceptScalar validates the field's exampleValue against the field's own constraints.
6. If validation fails, wouldAcceptScalar returns a message explaining the failure. A Violation record is created containing details of the failure: the operation, field path, example value, and the constraint that failed.
7. By default, the validator collects all violations and returns them as a list, which is surfaced as a warning to the operator. The import process is not blocked, allowing the operator to proceed and correct the contract later. An alternative validateOrThrow method exists to provide a hard failure if required.

API Reference

The WsdlContractRoundTripValidator service exposes two public methods.

collect

Runs the validation process and returns a list of any violations found. This is the non-blocking variant used during the standard "Prepare Service Workspace" flow, where findings are surfaced as warnings.

Returns

A List of WsdlContractValidationException.Violation objects. The list is empty if no violations are found. It is never null.

validateOrThrow

Runs the validation process and throws an exception if any violations are found. This is a blocking variant for callers that require a strict validation gate.

Throws

WsdlContractValidationException if one or more violations are found. The exception contains the list of violations and carries the error code S2R-ADM-0612.

Violation Report Structure

When a field's example fails its own validation, a WsdlContractValidationException.Violation object is created. A list of these objects constitutes the validation report. The structure of each violation is detailed below, which helps an operator identify the problematic field in the WSDL.

Example Violation

The source does not provide a full, runnable example. However, a generated violation for a field trackingID in the submitOrder operation's request might look like this conceptually:

{
  "operationName": "submitOrder",
  "surface": "request",
  "path": "body.submitOrder.trackingID",
  "exampleValue": "ID-12345",
  "pattern": "[A-Z]{3}-\\d{5}",
  "xsdType": "xs:string",
  "reason": "Value 'ID-12345' does not match pattern '[A-Z]{3}-\\d{5}'"
}

Troubleshooting

Error Code S2R-ADM-0612

If the validateOrThrow method is used, a WsdlContractValidationException with the error code S2R-ADM-0612 is thrown upon finding validation failures. The exception message contains a formatted list of all violations found, up to a limit of 50.

To resolve this, inspect the violation details provided in the error message. Each violation pinpoints the exact operation, field path, and constraint that failed. The issue typically lies in a mismatch between the constraints defined in the WSDL (e.g., a restrictive pattern or maxLength) and the example data that the platform generates. The API publisher may need to adjust the WSDL schema to be more permissive or correct a faulty constraint.

Truncated Violation List

The validator will stop collecting violations after it finds 50 (MAX_VIOLATION_DETAIL). If you receive a report with 50 violations, be aware that more may exist in the contract. It is recommended to fix the reported issues and re-run the import to see if additional violations are found.

Constants

The validator defines the following internal constant.

See Also

• com.specaria.s2r.admin.wsdl.WsdlContractBuilder: The component that generates contracts from a WSDL before this validator is run.
• ContractExampleService: The service used to generate example values for contract fields.
• SoapMessageMapper: The component containing the runtime scalar validation logic (wouldAcceptScalar) that this validator reuses.

All SOAP-to-REST docs