Matches

The matches constraint validates that a text value conforms to a specified regular expression.

This constraint is especially useful for enforcing naming conventions, identifier formats, or complex patterns that cannot be expressed with simpler constraints such as minimum, chars, or in.

Type Matrix

The following table summarizes which node types support the matches constraint.

Node Type

S

Value Type

Details

Integer

Boolean

Float

Text

RegEx

The text value must match the given regular expression.

Date

Time

DateTime

Bytes

TimeDelta

RegEx

Value

ValueList

ValueMatrix

Section

SectionList

SectionWithTexts

NotValidated

Rules for Matches

  1. Optional Support: Support for the matches constraint is optional.

    An implementation may omit this constraint entirely if the target platform does not provide suitable or safe regular expression support.

  2. Regex Dialect Must Be Documented: Because regular expression dialects vary between platforms, every implementation that supports matches must clearly document the supported syntax (for example, PCRE, POSIX, or RE2).

    Rule authors must be able to rely on documented behavior.

  3. Matching Semantics: By default, the regular expression is applied as a partial match.

    To require the entire text to match, validators must support the standard anchoring tokens:

    • ^ — beginning of the string

    • $ — end of the string

  4. Invalid Regular Expressions: If the provided regular expression is syntactically invalid according to the supported dialect, the validator must reject the Validation Rules document itself.

    This error occurs during rules processing, not during configuration validation.

Design Rationale

Regular expression support is intentionally left flexible. This allows implementers to reuse platform-native regex engines instead of mandating a specific one.

At the same time, requiring implementations to document the supported dialect ensures that rule authors know exactly which syntax and features they can rely on.

Example

The following example enforces a simple username format:

[api.user]
type: "text"
matches: /(?i)^[a-z][-_0-9a-z]{2,31}$/

[api]
user: "Example_01"

[api]
user: "_bad"   # ERROR: Must start with a letter and be 3–32 characters long.