Mental Model
Understanding four concepts is enough to predict how the library behaves: rules, validators, execution, and metadata.
Rules
A rule is a small object that:
- reads a value through an
IPropertyAccessor<T, TProperty>; - decides whether the value is valid;
- adds a
ValidationErrorto a collector when it is not.
Rules are stateless after configuration and can be reused across validation calls. Built-in rules cover presence, comparison, strings, dates, collections, and property comparison.
Validators
A fluent validator is a Validator<T> that builds an ordered set of rules in Configure. A
generated validator is a partial class emitted from attributes; it builds the same rule set.
Both implement IValidator<T>, which combines ISyncValidator<T> and IAsyncValidator<T>.
The validator is the unit you register in DI and resolve in a host.
Execution
Validate and ValidateAsync create a ValidationContext<T> and a pooled
ValidationErrorCollector, run the selected rule groups in order, and return a
ValidationResult.
- Sync rules run on both paths.
- Async rules run only on the async path.
- Async-only validators throw on the sync path.
- Rule sets select named groups; when a set is selected, ungrouped rules run only if
defaultis included. - Cascade controls whether a member continues after a failure.
- Fail-fast stops the whole validation at the first error.
- Conditions gate individual rules or groups.
- Dependent rules run only when the preceding rule passed.
The happy path is allocation-free after warmup: the collector and root context data are pooled per thread, and rule selection returns the original rule array when no filters apply.
Metadata
Every fluent and generated validator implements IValidationDescriptorProvider. Describe()
returns a frozen IValidationDescriptor containing members, rule kinds, message keys, severities,
conditions, and parameters.
Descriptors are the only source for JSON Schema, OpenAPI, and client-rule emission. They contain no delegates and no reflection objects.
Two authoring styles, one engine
| Concern | Fluent | Generated |
|---|---|---|
| Declaration | Validator<T>.Configure |
Attributes on the model |
| Rule order | Source order | Attribute order |
| Custom rules | AddCustomValidators() or Custom |
AddCustomValidators() partial hook |
| Descriptor | Built once per validator | Static frozen field |
| AOT | Explicit registration | Generated code |
Use fluent authoring for dynamic or context-heavy rules; use attributes for declarative models and compile-time validation of the rule configuration.
Integration packages
Integration packages never change engine semantics. They adapt the host:
- ASP.NET Core maps errors to ProblemDetails.
- MediatR runs validators in a pipeline behavior.
- DataAnnotations runs validators inside
ValidationAttributepipelines. - Blazor maps errors to
FieldIdentifiervalues. - Schema/OpenAPI/client packages consume descriptors.