Generate Example Strings from Regular Expressions

Overview

The RegexExampleGenerator is a utility that generates a single, representative string value that conforms to a given regular expression.

This component solves a specific problem encountered during the import of API contracts (e.g., from WSDL files). When a contract field specifies a data type (like xsd:int) and a constraining regular expression (xsd:pattern), standard example generators might produce a value that satisfies the type (e.g., 1) but not the pattern (e.g., a YYYYMMDD format). This mismatch causes contract import to fail with a validation error (S2R-ADM-0612), blocking an otherwise valid API definition.

The RegexExampleGenerator is invoked by the contract import service to seed example values for fields with xsd:pattern facets. It takes a regular expression and optional length constraints as input and produces a matching string. The calling service must then re-validate this generated string against all other facets of the field (such as numeric ranges or total digit counts) before use.

How it works

The generator processes a regular expression in two main phases: parsing the pattern into an internal structure and then rendering that structure into an output string according to specific policies.

flowchart TD
    A[API Contract with xsd:pattern] --> B(Regex Example Generator);
    B -- 1. Parse Regex --> C(Internal Representation - AST);
    C -- 2. Render with Policies --> D{Apply Quantifier & Length Policies};
    D -- Smallest non-empty count --> E;
    D -- Respect maxLength budget --> E;
    D -- Grow toward targetLength --> E(Generated Example String);
    E --> F{Is generation successful?};
    F -- Yes --> G[Return generated string];
    F -- No --> H[Return empty];

Pattern Parsing

1. Sanitization: The input pattern is first stripped of leading/trailing whitespace and any non-escaped ^ (start of string) and $ (end of string) anchors.
2. AST Construction: A parser analyzes the sanitized pattern and builds an Abstract Syntax Tree (AST) representing its components.
3. Supported Constructs: The parser is designed to handle the subset of regular expression features commonly found in XSD pattern facets:
   • Literals (e.g., a, 1)
   • Wildcard (.)
   • Escaped characters (\d, \w, \s, \D, \W, \S) and literal escapes (\-, \.)
   • Character classes ([...]) and negated character classes ([^...]), including ranges ([a-z])
   • Grouping, both capturing ((...)) and non-capturing ((?:...))
   • Alternation (|)
   • Quantifiers (?, *, +, {m}, {m,}, {m,n})

If the parser cannot process the entire input string, it is considered a syntax error, and the generator returns an empty result.

String Rendering

Once the AST is built, the generator traverses the tree to render the final string. The rendering process is guided by a set of deterministic policies to produce a useful, representative example.

Quantifier Policy

To generate a meaningful example, the generator follows a "smallest non-empty" rule for quantifiers.

• It renders the minimum number of repetitions required by the quantifier (the min value).
• If the minimum is zero (as in * or ?), it renders one repetition instead of zero. This prevents the generation of an empty string, which, while technically matching the pattern, is often an invalid value for a typed field (e.g., a number).
• The number of repetitions is capped at 64 to prevent excessive output from unbounded quantifiers (e.g., a{5,}).

Length-Aware Rendering

The generate(String, Integer, Integer) method provides length-aware generation to satisfy co-declared minLength and maxLength facets.

• maxLength: This acts as a hard budget. If a repetition would cause the generated string to exceed this length, the number of repetitions is reduced, potentially down to the quantifier's minimum. Optional groups that do not fit within the budget are omitted.
• targetLength: This acts as a preferred length. The generator will increase the number of repetitions for a group beyond its minimum to approach this target, as long as the maxLength budget is not exceeded.

Character Selection

When a pattern allows for multiple characters, the generator makes a deterministic choice:

• Character Class [...]: It prefers a digit, then a letter, then the first character defined in the class.
• Negated Class [^...]: It selects the first character from the pool 0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz that is not in the negated set.
• Escapes: It uses a fixed representative for common escapes (e.g., 0 for \d, A for \w).
• Wildcard .: It renders the character A.

Alternation (|)

For alternation, the generator first attempts to use the first branch in the sequence (e.g., a in a|b). If the minimum length of the first branch exceeds the available length budget, it will iterate through subsequent branches to find one that fits.

Example: Generating a Length-Constrained Phone Number

Consider a field PelephoneNo with the following constraints in an API contract:

• Pattern: 0\d([\d]{0,1})([-]{0,1})\d{7}
• minLength: 9
• maxLength: 10

A length-blind generation might produce "000-0000000". This string is 11 characters long, which matches the pattern but violates the maxLength of 10. This would cause the contract import to fail.

By using the length-aware generator, we can produce a compliant example.

// The pattern for the field
String pattern = "0\\d([\\d]{0,1})([-]{0,1})\\d{7}";

// The length constraints from the contract
Integer minLength = 9; // Used as the targetLength
Integer maxLength = 10;

// Generate the example
Optional<String> example = RegexExampleGenerator.generate(pattern, minLength, maxLength);

// Expected result: Optional.of("0000000000")
// This string is 10 characters long, satisfying both the pattern and the maxLength.
// The generator shrinks the optional groups (the extra digit and the hyphen) to fit the budget.

API Reference

The RegexExampleGenerator class exposes two static methods for generating examples.

generate(String rawPattern)

Generates a representative string from a regular expression without considering external length constraints.

Returns: An Optional<String> containing the generated example. Returns Optional.empty() if the pattern is null, blank, or contains unsupported constructs.

generate(String rawPattern, Integer targetLength, Integer maxLength)

Generates a representative string that attempts to adhere to minLength and maxLength constraints.

Returns: An Optional<String> containing the generated example. Returns Optional.empty() if the pattern is null, blank, contains unsupported constructs, or is unsatisfiable within the given constraints. With both targetLength and maxLength set to null, the output is identical to generate(String).

Troubleshooting

Generation Returns Empty

The generate methods return Optional.empty() to signal that an example could not be produced. This allows the calling service to fall back to a different example generation strategy. This can happen for several reasons:

• The input rawPattern is null or consists only of whitespace.
• The pattern contains syntax that the generator does not support (e.g., backreferences).
• The pattern has a syntax error, such as an unterminated group ( or character class [.
• A negated character class [^...] is unsatisfiable because it excludes all characters in the generator's fallback pool.

Generated Value Fails Validation

The generator guarantees that the output string will match the subset of regex syntax it supports. It does not guarantee that the string will satisfy other, co-declared contract facets. For example, for a pattern like \d{5} on an xsd:int field with a maxInclusive bound of 50000, the generator might produce "00000" or "11111", but it is not aware of the numeric bound. The caller is responsible for this final validation step.

S2R-ADM-0612 Error on Import

The S2R-ADM-0612 error ("value does not match pattern") is precisely what this generator is designed to prevent. If you still encounter this error on contract import for a field with a pattern, it may indicate:

1. The RegexExampleGenerator failed to produce a value for the pattern (see "Generation Returns Empty"), and the system fell back to a non-compliant default example.
2. The pattern uses constructs that are not supported by this generator.

All SOAP-to-REST docs