Contract Validation Overrides

Overview

The Contract Validation Override service provides methods for managing the validation rules applied to the request and response schemas of an API operation. It allows an API publisher to inspect, preview, and permanently modify field-level constraints such as regular expressions, string lengths, and numeric ranges.

This service solves the problem of needing to enforce validation rules that are stricter or different from those originally defined in an operation's base contract (e.g., from an imported WSDL). It operates on the internal contract representation and allows for granular, field-by-field adjustments.

The service has three primary functions:

1. Describe (describe): Fetches and presents the current validation rules for all fields in an operation's request and response schemas.
2. Preview (applyPreviewOverrides): Simulates the effect of applying one or more rule overrides to a schema without persisting the changes. This is useful for UI previews.
3. Update (updateFieldRule): Persistently applies a single validation rule override to a field in an operation's contract, regenerates the active configuration, and updates the contract's checksum.

How it works

The service modifies a structured JSON representation of the API contract. Changes are applied by traversing the schema tree to locate a specific field and then updating its constraint properties.

Describing Contract Fields

When describe is called with an operationId, it performs the following steps:

1. Retrieves the OperationContractRecord for the specified operation.
2. Calls the ContractExampleService to generate a descriptive list of all fields for both the request and response schemas.
3. Reads any legacy validation regexes stored in the operation_mapping table. These regexes were created by a different mechanism but are still active.
4. Normalizes the paths of the legacy regexes and the contract fields to a common format (a list of path segments) to allow for matching. Path formats like a.b.c, a/b/c, and a.b[0].c are all converted to a comparable segment list.
5. Annotates the field list with any matching legacy regexes, marking them with a mappingRegexOrigin of operation-mapping.
6. Returns a complete view of the operation, including its ID, key, and the annotated lists of request and response fields with their current validation rules.

Applying a Field Rule Update

The updateFieldRule method applies a permanent change to an operation's contract within a database transaction.

flowchart TD
    subgraph updateFieldRule Process
        A[API Publisher Call] --> B(Validate Inputs);
        B --> C{Input Valid?};
        C -- No --> D[Return Error];
        C -- Yes --> E[Fetch Operation Contract];
        E --> F[Deep-copy Schemas];
        F --> G[Find Target Field by Path];
        G --> H{Field Found?};
        H -- No --> D;
        H -- Yes --> I[Apply New Constraints];
        I --> J[Recalculate Schema Checksum];
        J --> K[Persist Updated Schemas];
        K --> L[Regenerate Active Mapping];
        L --> M[Describe Updated Contract];
        M --> N[Return New Contract View];
    end

The process is as follows:

1. Input Validation: The service first validates the provided parameters. It requires a valid side (request or response), a non-blank fieldPath, and logically consistent constraint values (e.g., minLength cannot be greater than maxLength).
2. Fetch and Copy: It retrieves the current contract and creates a deep copy of its request and response schemas to avoid modifying the original objects in memory.
3. Locate Field: The service traverses the target schema (request or response) based on the fieldPath. The path is a dot-separated string (parent.child) that can include array accessors (array[0].field).
4. Apply Constraints: Once the target field node is found, the new constraints are applied.
   • Providing a null or empty value for a constraint will remove it from the field.
   • When a pattern (regex) is overridden for the first time, the original pattern from the base contract is preserved in a new baselinePattern property. This ensures the original WSDL-defined regex is not lost.
5. Update Checksum: After modifying the schema, the service removes the old contractChecksum field, calculates a new SHA-256 checksum of the entire schema object, and adds it back as the contractChecksum property. This checksum tracks changes to the contract structure and rules.
6. Persist Changes: The updated request and response schemas are saved to the database.
7. Regenerate Mapping: The service triggers a regeneration of the active operation mapping to ensure the runtime uses the newly updated schemas.
8. Return Result: Finally, it calls the internal describe logic to return a fresh view of the newly modified contract.

Previewing Overrides

The applyPreviewOverrides method allows for a non-persistent "dry run" of changes. It accepts the current schemas and a list of FieldRuleOverride objects. It performs the same deep-copy, field-finding, and constraint application logic as updateFieldRule for each override, including the checksum refresh. However, it does not persist any changes to the database. It returns the modified schema objects, which can be used to show a user what effect their proposed changes would have.

API Reference

The service exposes the following public methods for managing contract validation overrides.

describe

Fetches a detailed description of an operation's contract, including all fields and their validation rules.

Map<String, Object> describe(UUID operationId)

Parameters

Returns

A Map containing the operation's metadata and annotated lists of requestFields and responseFields.

updateFieldRule

Applies a persistent validation rule change to a single field in an operation's contract.

Map<String, Object> updateFieldRule(UUID operationId, String side, ...)

Parameters

Returns

A Map representing the new state of the contract, identical in structure to the output of the describe method.

applyPreviewOverrides

Applies a list of overrides to the provided schemas in-memory to generate a preview of the changes.

SchemaOverrideResult applyPreviewOverrides(Map<String, Object> requestSchema, Map<String, Object> responseSchema, List<FieldRuleOverride> overrides)

Parameters

Returns

A SchemaOverrideResult object containing the modified requestSchema and responseSchema maps.

Field Rule Override Structure

The FieldRuleOverride object is used to specify a set of validation constraints for a single field. It is used by the applyPreviewOverrides method.

public record FieldRuleOverride(
    String side,
    String fieldPath,
    List<String> enumValues,
    String pattern,
    Integer length,
    Integer minLength,
    Integer maxLength,
    String minInclusive,
    String maxInclusive,
    String minExclusive,
    String maxExclusive,
    Integer totalDigits,
    Integer fractionDigits
) {}

Troubleshooting

When calling the service methods, you may encounter the following error conditions, which are reported by throwing an IllegalArgumentException.

Internal processing failures, such as an inability to serialize or checksum the contract, will result in an IllegalStateException.

See Also

• Contract Field and Example Service: The service used internally to describe contract fields.
• Bulk Validation Regex Application: A related service for applying validation regexes from a bulk source.

All SOAP-to-REST docs