Validation rule expressions

Validation rules are object-level checks that run on entity instance create, update, and import. Each enabled rule holds one boolean expression: it must return TRUE for the record to save. A FALSE result blocks the save and returns the rule’s failure message. Rules run in ascending sort order, before any C# business logic, and the first failing message is returned.

Choosing the right check

• Use a field’s RequiredWhen condition when the only requirement is that one field has a value.
• Use a validation rule for everyday consistency checks that describe the record as a whole — required-if rules, ranges, date ordering, text quality, first-level reference checks, regex checks — or when the check compares multiple values, checks a reference, or needs a tailored failure message.
• Use a C# validation function when the logic needs orchestration or goes beyond the expression profile below.

Expression profile

A validation expression can use:

• scalar fields of the record’s primary table;
• first-level reference paths such as Customer.DisplayName;
• the variables @currentUserId, @today, @today+7d, and @today-7d;
• the shared operators — comparisons, AND/OR/NOT, null/empty checks, text operators, IN, NOT IN, BETWEEN;
• the validation-only function MATCHES(value, "regex") (.NET regex, case-sensitive by default, (?i) for ignore-case);
• Classifier categories through the portable CATEGORY(...) literal.

Not supported: EXISTS and COUNT child-table forms (statement-only), aggregate functions, raw SQL, inverse-reference traversal, and deep reference chains.

MATCHES(Code, '^[A-Z]{3}-[0-9]{3}$')
DueDate IS NULL OR DueDate >= StartDate
DueDate IS NULL OR DueDate >= @today
Amount <= Customer.CreditLimit
Capability = CATEGORY('product-area', 'operations', 'platform')

Classifier fields support =, !=, IN, NOT IN, IS NULL, and IS NOT NULL. Exact and set comparisons do not match null. Field-to-field equality or inequality requires the same Classifier Catalog. Classifier fields are supported on the record and through a first-level Reference path. In the rule editor, place the cursor in the expression and choose Insert category to insert a portable CATEGORY(...) value; category names and breadcrumbs are for display only and are not used for matching. The logical root of a Classifier Catalog is not a category value, while stored non-leaf categories are valid values. See Classifier category values.

Failure messages

Message is the required fallback failure-message template, with optional per-locale translations (en, uk, de, pl, es). Templates use the same { … } placeholder style as presentation templates and can render:

• record fields: {Name}, first-level paths: {Customer.DisplayName};
• system values: {Number}, {DisplayName}, {Rule.Name}, {Rule.DisplayName}, {CurrentUserId}, {Today}.

A field referenced only in a failure message still counts as a schema dependency: it blocks field deletion and incompatible type changes the same way an expression reference does.

Authoring workflow

Validate the expression before saving with the validate-expression operation — the response reports validity plus structured errors (message, token, field path, and stable code). Rules are managed through the validation-rule endpoints of the Configuration API; reordering takes the full active rule set with row versions.

Creating or changing an expression that uses CATEGORY(...) requires Catalog Reader or management access to the referenced Classifier Catalog. A saved rule continues to validate records if that access is later removed, and its name, message, enabled state, and other metadata can still be updated while the expression remains unchanged.

Disabled rules stay stored but are not evaluated.