WSDL Contract Validation Exception (S2R-ADM-0612)

Overview

The WsdlContractValidationException is a runtime exception that signals an inconsistency found within a WSDL contract during the service creation process. It is thrown by the WsdlContractRoundTripValidator when an example value for a field does not conform to the validation rules (such as an XSD pattern or data type) defined for that same field in the schema.

This exception carries the error code S2R-ADM-0612.

The primary purpose of this exception is to detect and report self-contradictory definitions in a WSDL/XSD. For example, if a field is defined with a regular expression pattern that requires a 5-digit number, but its own declared default or example value is "abc", this validation will fail.

The exception provides detailed, structured information about each failure, enabling both automated processing by administrative UIs and clear, actionable guidance for the API publisher who needs to correct the source WSDL.

How It Works

When an API publisher provides a WSDL to create a new service, the platform performs a round-trip validation to ensure the contract is internally consistent.

flowchart TD
    subgraph Service Creation
        A[API Publisher imports WSDL] --> B(WSDL Round-Trip Validator)
        B --> C{For each scalar field...}
        C --> D[Get or generate example value]
        D --> E{Validate value against field's XSD constraints}
        E -- Validation Fails --> F[Create `Violation` record]
        F --> G{Any violations found?}
        E -- Validation Succeeds --> C
        G -- No --> L[Service workspace created successfully]
        C -- All fields checked --> G
        G -- Yes --> H{Is validation configured as blocking?}
        H -- Yes --> I[Throw `WsdlContractValidationException`]
        I --> J[Fail with error S2R-ADM-0612]
        J --> K[Service workspace NOT created]
        H -- No --> M[Attach violation details as warnings]
        M --> L
    end

The validation flow is as follows:

1. The WsdlContractRoundTripValidator processes the WSDL and its associated schemas.
2. For each scalar field (a simple field, not a complex object) in the request and response structures, the validator obtains an example value. This value may be an explicit default or example from the XSD, or it may be generated by the platform if none is provided.
3. The validator then tests this example value against the constraints defined for that very field, such as its XSD data type (xsdType) or any regular expression pattern facet.
4. If the example value fails its own validation, a Violation record is created containing details of the failure.
5. After checking all fields, if any violations were recorded, the system's behavior depends on its configuration:
   • Blocking Failure: A WsdlContractValidationException is thrown, which halts the service creation process. The API response will contain the error code S2R-ADM-0612 and a structured details object.
   • Non-Blocking Warning: The service workspace is successfully created, but the validation failures are attached to the success response as a list of warnings. This allows the API publisher to proceed but alerts them to issues that must be corrected.

Error and Warning Payload Structure

When this validation fails, the details are returned in a structured format within the API response. If the error is blocking, the details appear in the error.details object. If it is a non-blocking warning, a similar structure is included elsewhere in the successful response.

The payload contains a list of all violations found. Each violation includes the location of the field, the problematic value, the constraint it failed, and human-readable guidance on how to fix it.

Example Payload

Below is an example of the structured details returned for two violations. This structure is used for both blocking errors and non-blocking warnings.

{
  "code": "S2R-ADM-0612",
  "warningCount": 2,
  "message": "Service workspace prepared. 2 fields' example values do not match their required formats — the service is usable, but review the field mapping before going live. See the per-field guidance below:\n  • operation 'getUser' (request) field '$.user.zipCode': example value 'ABC' must match pattern [0-9]{5} (string) — Value 'ABC' does not match pattern '[0-9]{5}'\n  • operation 'getUser' (response) field '$.user.id': example value 'not-a-number' is invalid — 'not-a-number' is not a valid 'integer' value",
  "warnings": [
    {
      "operation": "getUser",
      "surface": "request",
      "fieldPath": "$.user.zipCode",
      "exampleValue": "ABC",
      "pattern": "[0-9]{5}",
      "xsdType": "string",
      "reason": "Value 'ABC' does not match pattern '[0-9]{5}'",
      "guidance": "This field requires its value to match the format [0-9]{5}. Check the field's definition in the source XSD: either the example/default value declared there does not match this pattern, or the pattern is too strict. Adjust whichever is wrong, then re-import the WSDL. If the XSD looks correct, this is likely a platform example-generation issue — report it to support with the operation and field name above."
    },
    {
      "operation": "getUser",
      "surface": "response",
      "fieldPath": "$.user.id",
      "exampleValue": "not-a-number",
      "xsdType": "integer",
      "reason": "'not-a-number' is not a valid 'integer' value",
      "guidance": "The example value for this field is not a valid integer value. If the source XSD declares an explicit example/default for this field, correct it there and re-import. Otherwise this is a platform example-generation issue — report it to support with the operation and field name above (the field's WSDL type definition does not need to change)."
    }
  ]
}

Payload Field Reference

The structured details payload contains the following fields.

Top-Level Fields (Error)

When returned as a blocking error, the error.details object contains these fields.

Top-Level Fields (Warning)

When returned as a non-blocking warning, the payload contains these fields.

Violation/Warning Item Fields

Each object in the violations or warnings array has the following structure.

Troubleshooting

When you encounter the S2R-ADM-0612 error or warning, it indicates a mismatch between a field's example value and its own constraints within the WSDL/XSD. Use the guidance provided for each violation to determine the fix.

There are two primary causes, which can be distinguished by the presence of the pattern field in the violation details.

Case 1: Violation includes a pattern

This is the most common cause. The field's example value does not match the regular expression defined in its XSD pattern facet.

To resolve:

1. Inspect the field's definition in the source XSD file.
2. Compare the exampleValue from the error details with the pattern.
3. Decide which is incorrect:
   • If the XSD declares an explicit example or default value for the field, and that value is wrong, correct it to match the pattern.
   • If the pattern is too strict or incorrect for the intended values, adjust the regular expression.
4. After correcting the source XSD, re-import the WSDL.
5. If you believe the XSD is correct and the platform generated an invalid example, contact support and provide the operation name, field path, and pattern.

Case 2: Violation does not include a pattern

The failure is due to a base data type mismatch. For example, the value "text" was provided for a field of type integer.

To resolve:

1. Check if the source XSD provides an explicit example or default for this field. If it does, it is likely invalid for the field's xsdType. Correct the value in the XSD and re-import.
2. If the XSD does not provide an explicit example, the platform likely generated an incompatible one. This may indicate a platform issue. Report the problem to support, including the operation name, field path, and xsdType. The field's type definition in the WSDL does not need to be changed.

See Also

• WsdlContractRoundTripValidator: The component responsible for performing this validation and throwing the exception.

All SOAP-to-REST docs