Rules and Messages
Rule families
| Family | Examples |
|---|---|
| Presence | NotNull, Null, NotEmpty, NotDefault, Empty |
| Comparison | Equal, NotEqual, GreaterThan, GreaterThanOrEqual, LessThan, LessThanOrEqual, InclusiveBetween, ExclusiveBetween, MultipleOf |
| Strings | Length, MinimumLength, MaximumLength, ExactLength, Matches, Contains, StartsWith, EndsWith, EmailAddress, CreditCard, Phone, Url, IPAddress, Base64String, FileExtensions |
| Collections | Count, MinCount, MaxCount, Unique, ForEach, Where, WhereAsync |
| Dates | Before, After |
| Property comparison | Equal, NotEqual, GreaterThan, GreaterThanOrEqual, LessThan, LessThanOrEqual against another property |
| Domain (optional) | Iban, VatNumber, PostalCode, NationalId, PasswordStrength, Uuid, Ulid |
| Custom | Must, MustAsync, Custom, CustomAsync |
NotEmpty does not treat value-type defaults (0, false, default(DateTime)) as empty. Use
NotDefault() when those values must be rejected explicitly.
The full list with parameters and message keys is in the rule reference.
Messages
Rules carry a default message key. WithMessage sets ValidationError.Message and marks it as
authored, so the localization pipeline keeps the authored text and does not replace it with a pack
template. Rules without an authored message resolve MessageKey through the packs. To change
localized default text, override the key in the message pack; see
Localization.
builder.RuleFor(x => x.Email, nameof(Customer.Email))
.NotEmpty()
.WithMessage("Email is required.")
.WithCode("EMAIL_REQUIRED")
.WithSeverity(ValidationErrorSeverity.Warning)
.WithName("Email address")
.WithState(new { source = "signup" });
Precedence for the reported member name:
- the string overload of
WithName/OverridePropertyNamereplacesValidationError.MemberName(and therefore the default{PropertyName}); WithName(Func<T, string>)changes the{PropertyName}parameter only;- otherwise
MemberNameis the code-facing path (Address.Street,Lines[0].Quantity).
ValidationOptions.DisplayNameResolver changes only the {PropertyName} message parameter; it
does not change MemberName. A rule-level override wins over the resolver.
Dynamic messages and names
Messages and display names can be computed from the instance that failed validation:
builder.RuleFor(x => x.Email, nameof(Customer.Email))
.NotEmpty()
.WithMessage(x => $"Email for {x.Name} is required.");
builder.RuleFor(x => x.Email, nameof(Customer.Email))
.NotEmpty()
.WithMessage((x, context) => $"{context.GetFullPath(nameof(Customer.Email))} is required.");
builder.RuleFor(x => x.Email, nameof(Customer.Email))
.NotEmpty()
.WithName(x => $"Email for {x.Name}");
builder.RuleFor(x => x.Email, nameof(Customer.Email))
.NotEmpty()
.OverridePropertyName(x => $"email-{x.Name}");
WithMessage(Func<T, string>)andWithMessage(Func<T, ValidationContext<T>, string>)run only when the rule fails. Anullor blank result falls back to the static message/default message.WithName(Func<T, string>)changes only the{PropertyName}parameter and leavesMemberNameunchanged. The string overload keeps its historical alias behavior forOverridePropertyName.OverridePropertyName(Func<T, string>)changesMemberNameas well.- A blank dynamic name falls back to the static override, the global resolver, or the code-facing member name.
- Options apply to composite rules too; the factory receives the parent instance and context.
ValidationOptions.DisplayNameResolverForInstance is the instance-aware resolver. It receives
(Type, memberName, instance) and takes precedence over the legacy DisplayNameResolver when it
returns a non-empty name.
Localization precedence: an authored ValidationError.Message (from WithMessage, attribute
messages, or explicit custom messages) wins over a matching message-pack template. A rule without
an authored message resolves its MessageKey through the packs; the pack template is the normal
path for generated rules.
Nested, collection, and child-rule options
WithMessage, WithCode, WithSeverity, WithState, and WithName/OverridePropertyName also
apply to composite rules:
SetValidator(...)andForEach(...)options apply to every error emitted by the child.ChildRules(...)options apply to every inline child error.- The string overload of
WithNamereplacesValidationError.MemberNamefor every emitted error; use it deliberately when collapsing a child path to one field. The delegate overload changes the display name only.
Options must directly follow the rule they configure. Configure them before When/Unless or
DependentRules; applying them after such a modifier throws InvalidOperationException instead of
silently doing nothing.
Input sanitization
Sanitization is opt-in preprocessing that runs before validation rules, not a rule itself.
Declare it with [Sanitize] on a property (or on the class for every writable string member
without its own [Sanitize]), or register it in fluent code with a setter:
[Sanitize(Trim = true, NormalizeWhitespace = true)]
public string? Bio { get; set; }
builder.RuleFor(static x => x.Name, nameof(User.Name), static (m, v) => m.Name = v!)
.Sanitize(Sanitize.Trim, Sanitize.ToUpperInvariant)
.NotEmpty();
Available operations: Trim, NormalizeWhitespace, RemoveControlChars, ToUpper/ToLower
(invariant by default, explicit CultureInfo opt-in), and Sanitize.EachElement(...) for
IList<string?> members. SanitizeOptions bundles the flags; [Sanitize] mirrors them with an
optional culture name. Whole-model cleanup uses builder.Sanitize(...) with an Action<T> or
ISanitizer<T>.
Sanitization mutates the model in place before rules run; Validate on a model with
[Sanitize] is an explicit preprocessing contract, never silent. Members without an accessible
non-init setter are rejected at build time with VAL0027; the same happens for non-string
members and unknown cultures. Sanitizers run even when rule-set filtering selects no rules, and
never appear in descriptors or client payloads. This is whitespace/casing/control-character
normalization only, not HTML or markup sanitization.
Message parameters
Every error carries a stable parameter dictionary for message templates and clients. The common
keys are PropertyName (display name or member path), PropertyValue (the validated value), and
PropertyPath (the full member path, including indexes). Rule-specific names include
ComparisonValue, ComparisonProperty, Min, Max, From, To, TotalLength, Length,
ExactLength, Pattern, Extensions, Values, EnumType, Count, Precision, Scale,
Divisor, Value, Country, Policy, MinLength, MissingRequirements, and CollectionIndex.
builder.RuleFor(x => x.Age, nameof(Customer.Age))
.InclusiveBetween(18, 120)
.WithMessage("{PropertyName} must be between {From} and {To}.");
builder.RuleFor(x => x.Tags, nameof(Order.Tags))
.ForEachElement(static tag => tag.NotEmpty())
.WithMessage("{PropertyPath}[{CollectionIndex}] is required.");
Use the MessageParameterNames constants instead of string literals. The old positional keys
("0", "1") remain available for compatibility. See the
rule reference for the complete table.
Error model
| Member | Meaning |
|---|---|
MemberName |
Code-facing path (Address.Street, Lines[0].Quantity), unless a rule-level WithName overrides it. |
Message |
Resolved or custom message. |
MessageKey |
Localization key. |
MessageParameters |
Stable named parameters (PropertyName, PropertyValue, PropertyPath, ComparisonValue, CollectionIndex, ...). |
ErrorCode |
Machine-readable code. |
Severity |
Info, Warning, or Error. |
CustomState |
Arbitrary state attached by the rule. |
Localization
Message keys resolve through the sibling Jeninnet.Localization pipeline. The
Jeninnet.Validation.Localization package supplies packs for 40 cultures. See
Localization.