Attribute Authoring
Attribute authoring declares rules on the model and lets the Roslyn source generator emit the validator.
Enable the generator
<PackageReference Include="Jeninnet.Validation.Analyzers" Version="1.0.0-preview.2"
PrivateAssets="all" />
Annotate the model
using Jeninnet.Validation.Attributes;
[Validate]
public sealed class Customer
{
[NotEmpty, Length(1, 100)]
public string Name { get; init; } = string.Empty;
[NotEmpty, Email]
public string Email { get; init; } = string.Empty;
[InclusiveBetween(18, 120)]
public int Age { get; init; }
}
The generator emits CustomerValidator in the model’s Validators namespace. [Validate] accepts an
optional target namespace; without it, the namespace is <model namespace>.Validators.
The generated class:
- implements
IValidator<Customer>; - implements
IValidationDescriptorProviderwith a per-instance descriptor built from the runtime rules; - has a parameterless constructor when no nested validators are injected;
- invokes
AddCustomValidators()before building the composite.
[Validate] also works on struct and record struct models:
[Validate]
public struct Money
{
[GreaterThanOrEqual(0)]
public decimal Amount { get; set; }
}
Generic model declarations are rejected with VAL0022; use a closed, non-generic model or a fluent
validator instead. This keeps generated type names and DI registrations deterministic.
Inheritance
When a derived class is annotated with [Validate], the generator includes the rules declared on
its base classes before the derived rules:
[Validate]
public class Contact
{
[NotEmpty] public string? Name { get; set; }
}
[Validate]
public sealed class Person : Contact
{
[NotEmpty] public string? Email { get; set; }
}
PersonValidator validates both Name and Email. A base type annotated with [Validate] does
not automatically generate validators for its derived types; annotate each type that needs a
validator. Annotated interfaces contribute their matching property rules to annotated implementing
classes.
For runtime-type dispatch and polymorphic collections, see Inheritance and polymorphism.
Rule metadata
Validation attributes expose optional named properties that flow to runtime errors and descriptors:
using System.ComponentModel.DataAnnotations;
using Jeninnet.Validation;
[Validate]
public sealed class Customer
{
[Email(
ErrorCode = "email_invalid",
Severity = ValidationErrorSeverity.Warning,
DisplayName = "Email address",
CustomState = "signup")]
public string? Email { get; init; }
[Display(Name = "Customer name")]
[NotEmpty]
public string? Name { get; init; }
[NotEmpty(OverridePropertyName = "renamed_name")]
public string? RenamedName { get; init; }
}
ErrorCode,Severity,DisplayName,OverridePropertyName, andCustomStateare available on every validation attribute because they live onValidationAttribute.CustomStateis a string in attributes because attribute arguments must be compile-time constants. Use the fluentWithStatefor arbitrary objects.[Display(Name = ...)]fromSystem.ComponentModel.DataAnnotationsis bridged to{PropertyName}; a rule-levelWithName/OverridePropertyNameor a configuredDisplayNameResolverwins over[Display].OverridePropertyNamechangesValidationError.MemberName;DisplayNamechanges only the{PropertyName}parameter.- The same values appear in
IValidationRuleDescriptor, client rules, and${"x-validation-rules"}schema advisory entries (x-validation-rules).
Use the generated validator
var validator = new CustomerValidator();
var result = validator.Validate(customer);
Register it explicitly (the AOT-safe pattern) or discover it through assembly scanning:
services.AddScoped<IValidator<Customer>, CustomerValidator>();
// Reflection-based discovery; not AOT-safe:
services.AddGeneratedValidators(typeof(CustomerValidator).Assembly);
Model-level validation shortcuts
By default the generator also emits a {Type}ValidationExtensions class in the model namespace (or
the TargetNamespace when one is set). It creates one static validator instance and exposes the
same contract through extension methods:
var result = customer.Validate();
var filtered = customer.Validate(new ValidationCallOptions { IncludeProperties = ["Name"] });
var asyncResult = await customer.ValidateAsync(cancellationToken);
var asyncFiltered = await customer.ValidateAsync(
new ValidationCallOptions { FailFast = true },
cancellationToken);
The extensions work for classes, structs, and record structs. They do not replace the DI path:
IValidator<T> remains the official integration contract, and the extensions hold no service
provider. Validators that require constructor injection (for example nested validators) keep the DI
path and do not get the shortcut. If the model already declares an instance Validate member,
normal C# overload resolution prefers the instance member. Disable the feature per model with
[Validate(GenerateModelExtensions = false)].
Custom rules in a generated validator
Attributes cannot express every predicate. The generator emits a partial void AddCustomValidators()
hook that runs before the composite validator is created. Add rules directly to the generated
_syncRules or _asyncRules lists:
using Jeninnet.Validation.Core;
using Jeninnet.Validation.Rules;
namespace MyApp.Models.Validators; // <model namespace>.Validators
public sealed partial class CustomerValidator
{
partial void AddCustomValidators()
{
_syncRules.Add(
new MustRule<Customer, string?>(
ValidatorFactory.Accessor<Customer, string?>(
static x => x.Name,
nameof(Customer.Name)),
static name => name != "admin",
"This name is reserved."));
}
}
The hook has no builder parameter; it is a partial method on the generated class, so it can access
the generated rule lists. Rules added this way execute normally and are described by Describe():
built-in rules and rules derived from SyncValidateRule/AsyncValidateRule expose their own
metadata. A rule that cannot do so appears as a Custom advisory entry with a reason and type.
To add explicit metadata for a custom rule, implement the generated ConfigureDescriptor hook:
using Jeninnet.Validation.Metadata;
public sealed partial class CustomerValidator
{
partial void ConfigureDescriptor(ValidationDescriptorBuilder builder)
{
builder.Member(nameof(Customer.Name)).Rule(
kind: "ReservedName",
messageKey: "ReservedName",
severity: ValidationErrorSeverity.Warning,
parameters: new Dictionary<string, object?> { ["Value"] = "admin" },
errorCode: "reserved_name",
displayName: "Customer name");
}
}
The descriptor hook adds data only. It does not add executable rules, and it cannot expose
delegates. The build-time client-rules catalog still reflects attributes only; use
ClientRulesWriter at runtime when custom descriptor entries must reach the client. For
context-heavy predicates, fluent Custom/CustomAsync rules remain the better choice.
Rule sets in attributes
Apply [RuleSet("Admin")] to a property or the model to place generated rules in a named set:
[Validate]
[RuleSet("Admin")]
public sealed class Customer
{
[NotEmpty]
public string Name { get; init; } = string.Empty;
[InclusiveBetween(0, 100)]
public int InternalScore { get; init; }
}
A property-level [RuleSet] wins over the class-level attribute. A rule-level named property wins
over both and applies to one rule only:
[NotEmpty(RuleSet = "Admin")]
public string? Code { get; init; }
Selecting ["Admin"] runs only that set; add "default" to include ungrouped rules. When no rule
sets are supplied, all rules run, including rules in named sets.
Conditions in attributes
[WhenCondition] and [UnlessCondition] gate generated rules on a synchronous method that must exist
on the containing type:
[Validate]
[WhenCondition(nameof(IsEditable))]
public sealed class Order
{
[WhenCondition(nameof(IsReasonRequired))]
public string? Reason { get; init; }
public bool IsEditable(Order instance) => instance.Reason != "cancelled";
public bool IsReasonRequired(Order instance) => instance.Reason != "draft";
}
The method must return bool and accept either (T instance) or
(T instance, ValidationContext<T> context). It may be an instance or static method. A property-level
condition wins over a class-level condition. Synchronous attribute conditions run on both Validate
and ValidateAsync.
[WhenAsyncCondition] and [UnlessAsyncCondition] gate rules on a method with the signature
Task<bool> MethodName(T instance, CancellationToken ct). The property-level condition wins over a
class-level condition. These rules run only on the async path; use ValidateAsync.
Value conditions
Three shortcuts cover the common "required or in range depending on another field" scenarios without writing a condition method:
[Validate]
public sealed class Order
{
public string? Mode { get; set; }
public bool IsGift { get; set; }
[RequiredIf(nameof(Mode), "Express")]
public string? Courier { get; set; }
[RequiredUnless(nameof(Mode), "Express")]
public string? PickupPoint { get; set; }
[ConditionalRange(nameof(Mode), "Business", 1, 10)]
public int Quantity { get; set; }
[RequiredIf(nameof(IsGift), true)]
public string? GiftMessage { get; set; }
}
[RequiredIf(other, value)]requires the member whenotherequalsvalue.[RequiredUnless(other, value)]requires the member whenotherdoes not equalvalue.[ConditionalRange(other, value, min, max)]applies an inclusive range whenotherequalsvalue.
A string or collection member is checked for emptiness; any other member is checked for null. The
comparison supports strings, Booleans, characters, all numeric types, enums, date/time types, Guid,
and TimeSpan. Numeric constants are compared numerically, so an int member matches a long
constant such as 1L. Date/time members accept parseable strings. The value must be a compile-time
constant.
When the property also carries [WhenCondition]/[UnlessCondition] (or the model carries a
class-level condition), both conditions must pass. [RequiredIf] and [RequiredUnless] can be
combined with other rules, but each attribute targets a simple member name on the same model; nested
paths and multiple values in one attribute are not supported. Invalid targets, unsupported values,
and duplicate attributes are reported at compile time as VAL0029–VAL0031.
These rules cannot be expressed in JSON Schema or client-side validation; generated descriptors mark
them as conditional, JSON Schema keeps them as advisory, and the client-rules export sets
serverOnly: true. See Known limitations.
Relative dates
[FutureDate] and [PastDate] validate against the current UTC time instead of a fixed threshold:
public sealed class Subscription
{
[FutureDate]
public DateTime StartsAt { get; set; }
[FutureDate(IncludeToday = true)]
public DateTimeOffset TrialEndsAt { get; set; }
[PastDate]
public DateOnly? CancelledOn { get; set; }
}
IncludeToday defaults to false, so the value must be strictly later (or earlier) than the
current instant; set it to true to allow equality. The current time comes from a TimeProvider
resolved through ValidationCallOptions.ServiceProvider, falling back to TimeProvider.System.
Comparisons are UTC and never convert to local time, so inject a fixed provider in tests. Supported
types are DateTime, DateTimeOffset, and DateOnly (and nullable variants); TimeOnly and other
types produce VAL0032. Null passes; add [NotNull] when presence is required. Relative-date rules
are server-only and remain advisory in JSON Schema.
Lifecycle hooks in attributes
[PreValidate] and [OnFailure] bind static methods on the model to the generated validator:
using Jeninnet.Validation;
using Jeninnet.Validation.Attributes;
using Jeninnet.Validation.Core;
[Validate]
[PreValidate(nameof(BeforeValidate))]
[OnFailure(nameof(AfterFailure))]
public sealed class Order
{
[NotEmpty] public string? CustomerName { get; set; }
public static bool BeforeValidate(
Order instance,
ValidationContext<Order> context,
ValidationErrorCollector errors) {
if (instance.CustomerName == "blocked") {
errors.Add(nameof(CustomerName), "blocked");
return false;
}
return true;
}
public static void AfterFailure(ValidationResult result) {
// audit or metrics; runs once when the merged result is invalid
}
}
PreValidateis static and returnsbool; it accepts(T, ValidationContext<T>)or(T, ValidationContext<T>, ValidationErrorCollector).- Errors added through the collector are merged with rule errors. Returning
falsestops rule evaluation. OnFailureis staticvoid(ValidationResult)and runs once after a failed result is known.- Declarative hooks have no async variants; use fluent
PreValidateAsync/OnFailureAsyncwhen async work is required.
Custom validators in attributes
[CustomValidator] delegates to a static method on a rules type:
using System.Threading;
using System.Threading.Tasks;
using Jeninnet.Validation;
using Jeninnet.Validation.Attributes;
public static class OrderRules
{
public static bool IsReserved(string? value) => value != "admin";
public static ValidationResult CheckCode(string? value)
{
var errors = new ValidationErrorCollector();
if (value == "bad")
{
errors.Add(string.Empty, "The code is not acceptable.");
}
return ValidationResult.FromErrors(errors);
}
public static ValueTask<bool> IsAvailableAsync(
string? value,
CancellationToken cancellationToken) =>
ValueTask.FromResult(value != "taken");
}
[Validate]
public sealed class Order
{
[CustomValidator(typeof(OrderRules), nameof(OrderRules.IsReserved))]
public string? CustomerName { get; init; }
[CustomValidator(typeof(OrderRules), nameof(OrderRules.CheckCode))]
public string? Code { get; init; }
[CustomValidator(typeof(OrderRules), nameof(OrderRules.IsAvailableAsync), IsAsync = true)]
public string? Reference { get; init; }
}
Supported synchronous signatures:
bool Method(TValue value)bool Method(TValue value, IServiceProvider services)ValidationResult Method(TValue value)ValidationResult Method(TValue value, IServiceProvider services)
Asynchronous rules add CancellationToken as the final parameter and return
ValueTask<bool> or ValueTask<ValidationResult>:
ValueTask<bool> Method(TValue value, CancellationToken cancellationToken)ValueTask<bool> Method(TValue value, IServiceProvider services, CancellationToken cancellationToken)ValueTask<ValidationResult> Method(TValue value, CancellationToken cancellationToken)ValueTask<ValidationResult> Method(TValue value, IServiceProvider services, CancellationToken cancellationToken)The method must be static; generic methods and
Task-returning methods are rejected.A
boolfalse result adds one error using the attribute message (or theMust/MustAsyncmessage key).ValidationResulterrors with an empty member name are attributed to the property; explicit paths are preserved.IServiceProvidercomes fromValidationContext<T>.ServiceProvider(supply it throughValidationCallOptions); it can benullwhen no provider was configured.A class-level
[CustomValidator]receives the whole model instance and reports a root error.Async custom rules run only on
ValidateAsync. A validator whose rules are all async is marked[AsyncOnlyValidator]and throws on synchronousValidate.Invalid signatures produce
VAL0020at compile time.
Rule order
Rules run in attribute order within a member. Keep presence rules before shape/comparison rules when
using CascadeMode.Stop or fail-fast.
Sanitization in attributes
[Sanitize] is preprocessing, not a rule. It runs before every rule on every Validate call and
never appears in descriptors:
public sealed class Customer
{
[Sanitize(Trim = true)]
[NotEmpty]
public string? Name { get; set; }
[Sanitize(ToUpper = true, Culture = "tr-TR")]
public string? Code { get; set; }
}
A class-level [Sanitize] applies to every writable string/IList<string> member without its
own [Sanitize]; a property-level attribute wins for that property. Members without an
accessible non-init setter, non-string members, and unknown cultures fail the build with
VAL0027. See Rules and messages for the fluent equivalent.
Skip validation
[SkipValidation] removes a member or a model type from generated validation. It is a marker, not
a rule: a skipped property produces no rules even when it carries other validation attributes, and
a skipped type produces no generated validator and is not validated when reached through [Nested]
or [ForEach].
[Validate("Shop")]
public sealed class Product
{
[NotEmpty]
public string? Name { get; set; }
[SkipValidation]
public string? LegacyCode { get; set; } // no rules are generated
[Nested]
public AuditedBy? Auditor { get; set; } // no nested validation when AuditedBy is skipped
}
[SkipValidation]
public sealed class AuditedBy
{
[NotEmpty]
public string? Name { get; set; }
}
Combining [SkipValidation] with validation attributes on the same property is almost always a
mistake; the generator reports VAL0028 and still drops every rule for that property. Use the
marker to opt out of generated validation while keeping existing annotations, for example when an
external platform attribute should be the only contract. The marker does not change fluent
validators or the ValidationStrategy runtime option: a manually configured validator still runs
unless the caller filters properties. On a minimal API handler parameter or an MVC action
parameter, [SkipValidation] skips request validation for that parameter.
AddRequestValidation<T>() and AddMvcValidation() honor the marker.
Verify
var descriptor = ((IValidationDescriptorProvider)new CustomerValidator()).Describe();
The generated descriptor is static, so repeated Describe() calls allocate nothing.