Constrained String Sampler for Schema-Compliant Examples

Overview

The ConstrainedStringSampler is a stateless utility that generates example string values that conform to a given set of schema constraints. It solves the problem of API specifications containing example values that are invalid according to the schema rules (pattern, length, minLength, maxLength) defined for those values.

This component is used internally by other platform services, such as the OpenAPI specification generator (OpenApiService) and the contract example generator (ContractExampleService), to ensure that generated examples are self-consistent and pass schema validation.

For an API publisher, this means that the example values shown in generated API documentation will be valid and usable. This prevents situations where an API consumer might try an example from the documentation only to have it rejected by the API gateway for violating schema rules that were also in the documentation.

How it works

The ConstrainedStringSampler generates a valid string by creating a list of candidate values and returning the first one that satisfies all provided constraints. If no candidate can be found, it returns a best-effort fallback value.

The core logic resides in the static sample method.

flowchart TD
    subgraph "Input"
        A[Base Value & Schema Constraints <br/>(pattern, min/max length)]
    end

    subgraph "Processing"
        B{Any constraints provided?}
        A --> B

        B -- No --> C[Return Base Value]

        B -- Yes --> D[Determine Target Length]
        D --> E[Generate Candidate List]
        E --> F{Iterate through candidates}

        subgraph "Candidate Generation"
            style E fill:#f9f,stroke:#333,stroke-width:2px
            E1[1. Heuristics for simple regex patterns]
            E2[2. Base Value, adjusted for length]
            E3[3. Simple repeating character strings ('111', 'AAA')]
            E4[4. Alternating alphanumeric string ('A1A1')]
            E5[5. Advanced regex generator for complex patterns]
        end

        F --> G{Is candidate valid?}
        G -- No --> F

        subgraph "Validation"
            style G fill:#ccf,stroke:#333,stroke-width:2px
            G1[Within length bounds?]
            G2[Matches regex pattern?]
        end

        G -- Yes --> H[Return First Valid Candidate]
    end

    subgraph "Output"
        F -- All candidates invalid --> I[Return Fallback Value <br/>(length-adjusted base value)]
        C --> Z[Final String Example]
        H --> Z
        I --> Z
    end

Generation and Validation Flow

1. Constraint Check: The process begins by checking if any constraints (pattern, exactLength, minLength, maxLength) are provided. If not, the original baseValue is returned immediately.
2. Target Length Calculation: If constraints exist, the sampler calculates a targetLength. This length respects exactLength if present, otherwise it is derived from the baseValue's length, minLength, maxLength, and a fallbackLength. The resulting length is always at least 1.
3. Candidate Generation: A list of potential strings is generated in a specific order of preference:
   • Pattern Heuristics: If a pattern is provided, the sampler first attempts to generate candidates using heuristics for common regular expressions (e.g., [0-9]+, [A-Z]{5}, \d{1,10}). This includes a generic handler for single character classes (e.g., [A-Za-z0-9_-]+).
   • Adjusted Base Value: The input baseValue is truncated or padded to meet the targetLength.
   • Simple Repeats: Simple strings of repeated characters are added (e.g., '111...', 'AAA...').
   • Alphanumeric: An alternating alphanumeric string is generated (e.g., 'A1A1A').
   • Advanced Regex Generation: For complex patterns involving groups or alternation, an external RegexExampleGenerator is invoked. This is a last-resort attempt and its results are added to the end of the candidate list.
4. Validation Loop: The sampler iterates through the list of candidates. For each candidate, it performs two checks:
   • It verifies the string's length is within the bounds defined by exactLength, minLength, and maxLength.
   • If a pattern was provided, it validates the string against the regular expression using the ContractPatternValidator.
5. Return Value: The first candidate to pass all validation checks is returned.
6. Fallback: If no candidate in the list satisfies all constraints, the sampler returns the length-adjusted baseValue as a final fallback. This fallback value will respect length constraints but may not satisfy the pattern constraint.

Example

This example demonstrates how the sampler corrects an example value that is too long for its schema constraint.

Given an input baseValue of "sample-SHILDA" (13 characters) and a maxLength constraint of 10.

Invocation:

String result = ConstrainedStringSampler.sample(
    "sample-SHILDA", // baseValue
    null,            // pattern
    null,            // exactLength
    null,            // minLength
    10,              // maxLength
    8                // fallbackLength
);

Execution:

1. Constraints are present (maxLength: 10), so the process continues.
2. The targetLength is resolved. The baseValue length (13) is greater than maxLength (10), so the targetLength is capped at 10.
3. A list of candidates is generated. The first non-pattern-based candidate is created by adjusting the baseValue. The adjustToLength method truncates "sample-SHILDA" to respect the maxLength of 10. The resulting candidate is "sample-SHI".
4. The candidate "sample-SHI" is validated. Its length is 10, which is not greater than maxLength (10). The length check passes.
5. There is no pattern to validate against.
6. As the first candidate is valid, it is returned.

Expected Result:

The method returns the string "sample-SHI".

API Reference

The component exposes a single static method, sample.

sample

public static String sample(String baseValue, String pattern, Integer exactLength, Integer minLength, Integer maxLength, int fallbackLength)

Fits a base string value to the supplied schema facets, returning a new string that satisfies the constraints.

Parameters

Returns

A String that satisfies the provided constraints. If no generated candidate is fully compliant, it returns a best-effort fallback string that respects length constraints but may not match the pattern.

Troubleshooting

Understanding Generation Failures

The ConstrainedStringSampler uses a series of heuristics to generate a valid example. While it covers many common cases, it is possible for it to fail to produce a string that satisfies a very complex pattern constraint.

If the sampler fails to find a valid candidate, it returns a fallback value. This fallback is the initial baseValue adjusted for length constraints (minLength, maxLength, exactLength). This fallback value is not guaranteed to match the pattern constraint.

The source code indicates that several improvements have been made to handle cases that previously failed:

• Complex Regex with Length Limits: A length-aware retry mechanism was added to the RegexExampleGenerator to handle patterns with optional groups that could otherwise generate a string exceeding maxLength.
• Custom Character Classes: A generic parser for bracketed character classes (e.g., [A-Z0-9-]{1,10}) was added to handle patterns not covered by the initial, more specific heuristics.

If you encounter an example in a generated specification that is invalid, it may be due to a pattern that is too complex for the sampler's current capabilities.

See Also

• ContractExampleService: A service that uses this sampler to generate examples for API contracts.
• OpenApiService: A service that uses this sampler to generate examples within OpenAPI specifications.
• ContractPatternValidator: The utility used internally by the sampler to check if a string matches a given regular expression.
• RegexExampleGenerator: A utility used by the sampler as a last resort to generate examples for complex regular expression patterns.

All SOAP-to-REST docs