Generate Schema-Compliant Example Strings

Overview

The ConstrainedStringSampler is a stateless utility component that generates example string values satisfying a given set of schema constraints. It takes a base string and schema facets—such as pattern, minLength, maxLength, and length—and produces a new string that complies with all of them.

This component solves a critical problem in API contract generation: ensuring that example values within a specification are themselves valid according to the schema they document. Without this, an API gateway or validation tool might reject a specification because its own examples violate its rules (e.g., an example string is longer than the specified maxLength).

ConstrainedStringSampler is a shared utility used by other internal components, such as ContractExampleService (for general contract example generation) and OpenApiService (for OpenAPI specification generation), to ensure consistent and valid example data.

How it works

The ConstrainedStringSampler operates through a single static method, sample, which follows a deterministic process of candidate generation and validation to find a suitable example string.

flowchart TD
    subgraph "Input"
        A[baseValue, pattern, length constraints]
    end

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

        B -- No --> C[Return baseValue]

        B -- Yes --> D[Resolve target length]
        D --> E[Generate candidate strings]

        subgraph "Candidate Generation Order"
            direction LR
            E1[1. Pattern-based heuristics]
            E2[2. Length-adjusted baseValue]
            E3[3. Generic fallbacks (e.g., "111", "AAA")]
            E4[4. Regex-based generator (last resort)]
        end
        E --> E1 --> E2 --> E3 --> E4

        F{Loop through candidates}
        E4 --> F

        subgraph "Validation"
            G{Is candidate valid?}
            H[Check length constraints]
            I[Check pattern match]
            G --> H --> I
        end

        F -- For each candidate --> G

        I -- Yes --> J[Return valid candidate]
        I -- No --> F
    end

    subgraph "Output"
        F -- No valid candidate found --> K[Return length-adjusted baseValue as final fallback]
        C --> L[Final String]
        J --> L
        K --> L
    end

The process is as follows:

1. Input & Initial Check: The sample method receives a baseValue string and several nullable constraint parameters (pattern, exactLength, minLength, maxLength). If no constraints are provided, it immediately returns the original baseValue.

2. Resolve Target Length: If constraints are present, the method first determines a targetLength for the output string. It prioritizes exactLength, then considers minLength and maxLength in relation to the baseValue's length or a fallbackLength. The resulting length is always at least 1.

3. Generate Candidates: The sampler creates an ordered list of potential example strings. The order is crucial, as the first valid candidate is always chosen.

   1. Pattern Heuristics: If a pattern is provided, it first attempts to generate simple, predictable strings based on common regex forms like \d{5}, [A-Z]+, or [0-9]{1,9}. This is handled by the patternCandidates method, which produces strings like "11111" or "AAAA". It includes a generic handler for any pattern of the form [character-class]{quantifier}.
   2. Adjusted Base Value: The original baseValue is adjusted to fit the targetLength and added to the list.
   3. Generic Fallbacks: Several hardcoded candidates are added: a string of repeating '1' characters, a string of repeating 'A' characters, and an alternating alphanumeric string (e.g., "A1A1A").
   4. Regex Generator: As a last resort for complex patterns (e.g., those with alternations or groups), it invokes RegexExampleGenerator to produce a matching string. This is added to the end of the candidate list to ensure that simpler, more readable heuristic-based examples are preferred.

4. Validate and Return: The method iterates through the list of candidates. For each one, it checks:

   • That the string is not null or blank.
   • That its length is within the bounds defined by exactLength, minLength, and maxLength.
   • If a pattern is specified, that the string matches the pattern (using ContractPatternValidator).

   The first candidate to pass all checks is immediately returned.

5. Final Fallback: If no candidate in the list satisfies all constraints, the method returns the baseValue adjusted for length, even if it does not match the pattern. This ensures the sampler always returns a string that at least meets the length requirements.

Example

Consider generating an example for a field with a maxLength of 10, where the unconstrained sample value is "sample-SHILDA" (13 characters).

The ConstrainedStringSampler would be invoked as follows:

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

Expected Result: "sample-SHI"

Explanation:

1. The sample method identifies that maxLength is 10.
2. The targetLength is resolved to 10, because the base value's length (13) is greater than the maxLength.
3. The first candidate generated is the baseValue adjusted for length. The adjustToLength function truncates "sample-SHILDA" to the first 10 characters.
4. The resulting candidate, "sample-SHIL", is validated. Its length (10) is not greater than maxLength (10), so it passes the length check.
5. Since no pattern was specified, this candidate is considered valid.
6. The method returns "sample-SHIL" as the result.

API Reference

The component exposes a single public static method.

sample

Generates a string that satisfies the supplied schema constraints.

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

Parameters

Returns

A String that satisfies as many of the provided constraints as possible. In cases where no candidate can be found to satisfy all constraints (e.g., a complex pattern), it returns a best-effort string that meets the length requirements.

Troubleshooting

The ConstrainedStringSampler is designed to always return a string and does not throw exceptions. However, the output may sometimes be unexpected.

Symptom: The generated example does not match the pattern constraint.

• Cause: This occurs when the sampler cannot find or generate any candidate string that satisfies both the pattern and the length constraints. In this scenario, its final fallback behavior is to return a length-adjusted version of the baseValue (or a default like "value"), which may not match the pattern. This prioritizes providing a value that fits length constraints over one that fits the pattern.

Symptom: The generated example is a simple repeating string like "11111" or "AAAAA".

• Cause: This is expected behavior. The sampler's candidate generation process is ordered to prefer simple, deterministic, and readable examples derived from heuristics. It only attempts to use a more complex RegexExampleGenerator as a last resort if none of the simpler candidates are valid.

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 internal utility used to check if a candidate string matches a given regular expression.
• RegexExampleGenerator: An internal utility used to generate example strings from complex regular expressions when simpler heuristics fail.

All SOAP-to-REST docs