Vali-Validation 3.0.0

Vali-Validation

Vali-Validation is a lightweight, zero-dependency fluent validation library for .NET 7, 8, 9, and 10. It provides a clean, expressive API for defining validation rules on your models, with full support for async validation, conditional rules, nested object validation, collection validation, cascade mode, error codes, custom rules, and seamless dependency injection — all without requiring any external dependencies beyond Microsoft.Extensions.DependencyInjection.Abstractions.

Installation

dotnet add package Vali-Validation

Quick Start

Define a validator by subclassing AbstractValidator<T> and configuring rules in the constructor:

using Vali_Validation.Core.Validators;

public class CreateUserDto
{
    public string? Name { get; set; }
    public string? Email { get; set; }
    public string? Password { get; set; }
    public int Age { get; set; }
}

public class CreateUserValidator : AbstractValidator<CreateUserDto>
{
    public CreateUserValidator()
    {
        RuleFor(x => x.Name)
            .NotEmpty()
            .MinimumLength(2)
            .MaximumLength(100);

        RuleFor(x => x.Email)
            .NotEmpty()
            .Email();

        RuleFor(x => x.Password)
            .NotEmpty()
            .MinimumLength(8)
            .HasUppercase()
            .HasLowercase()
            .HasDigit()
            .HasSpecialChar();

        RuleFor(x => x.Age)
            .GreaterThanOrEqualTo(18)
            .LessThan(120);
    }
}

Use the validator:

var validator = new CreateUserValidator();
var result = validator.Validate(dto);

if (!result.IsValid)
{
    foreach (var error in result.ToFlatList())
        Console.WriteLine(error);
}

// Async
var result = await validator.ValidateAsync(dto, cancellationToken);

// Throw on failure
validator.ValidateAndThrow(dto);
await validator.ValidateAndThrowAsync(dto, cancellationToken);

Available Rules

Modifiers

Message Templates

Error messages support {PropertyName} and {PropertyValue} placeholders:

RuleFor(x => x.Age)
    .GreaterThan(0)
    .WithMessage("'{PropertyName}' value '{PropertyValue}' must be positive.");

Severity (Warnings vs Errors)

By default, every rule failure is Severity.Error and makes IsValid false. Mark a rule as non-blocking with .WithSeverity(Severity.Warning):

public class OrderValidator : AbstractValidator<Order>
{
    public OrderValidator()
    {
        RuleFor(x => x.Email).NotEmpty(); // Severity.Error (default)

        RuleFor(x => x.Discount)
            .LessThanOrEqualTo(50)
            .WithSeverity(Severity.Warning)
            .WithMessage("Discount above 50% requires manager approval.");
    }
}

A Warning (or Info) failure still appears in result.Failures, but never makes IsValid false and never appears in the legacy Errors/ErrorCodes/ErrorsFor/HasErrorFor surface — those only ever reflect Severity.Error failures, so existing code that doesn't know about severity keeps working unchanged.

result.Failures serializes (via System.Text.Json, default options — no naming policy or converter required) as a single structured array:

{
  "isValid": false,
  "failures": [
    { "property": "Email", "message": "The Email field must be a valid email address.", "severity": "Error" },
    { "property": "Discount", "message": "Discount above 50% requires manager approval.", "severity": "Warning" }
  ]
}

.WithSeverity() scope: like .WithMessage()/.WithErrorCode(), it only affects the last rule added — including .MustAsync(...)/.DependentRuleAsync(...), which it now targets correctly. It has no effect on RequiredIf/EqualToProperty/other cross-property rules.

Migrating from v2.x

• If you never need Warning/Info severities, no code changes are required — Errors/ErrorCodes/ErrorsFor(...)/HasErrorFor(...)/FirstError(...)/IsValid all behave exactly as before.
• If you directly mutated result.Errors/result.ErrorCodes or assigned them to a variable typed as Dictionary<string, List<string>>, that will now fail to compile — both are now IReadOnlyDictionary<string, List<string>>. Read-only usage (indexer reads, iteration, ContainsKey) is unaffected.
• To read the new severity-aware data:

  // Old (v2.x): result.Errors["Email"]
  // New (v3.x):
  result.Failures.Where(f => f.PropertyName == "Email").Select(f => f.Message);
  

Localization

Built-in rule messages are available in English (default) and Spanish out of the box, resolved automatically from CultureInfo.CurrentUICulture — no configuration needed in an ASP.NET Core app with standard request localization.

// Automatic: resolves from CultureInfo.CurrentUICulture
var result = validator.Validate(dto);

// Explicit override for one call
var result = validator.Validate(dto, opts => opts.WithLanguage("es"));

// App-wide default (used when CurrentUICulture has no catalog entry)
ValiValidationOptions.Global.DefaultLanguage = "es";

Add your own language by registering a catalog at startup — a partial catalog is fine, any missing key falls back to English:

LanguageManager.RegisterLanguage("pt", new Dictionary<MessageKey, string>
{
    [MessageKey.NotEmpty] = "O campo {PropertyName} não pode estar vazio.",
    // ... remaining keys fall back to English until added
});

Known limitation: nested validators attached via SetValidator do not inherit an outer call's explicit .WithLanguage(...) override — each resolves independently from CultureInfo.CurrentUICulture, which is already consistent across nesting without any forwarding needed for the common case.

Global Configuration

ValiValidationOptions.Global configures app-wide defaults — set once at startup, before any concurrent validation runs:

ValiValidationOptions.Global.DefaultCascadeMode = CascadeMode.StopOnFirstFailure;
ValiValidationOptions.Global.DefaultLanguage = "es";
ValiValidationOptions.Global.DisplayNameResolver = name => name; // e.g. PascalCase → "Display Name"
ValiValidationOptions.Global.PropertyNameResolver = name => name; // e.g. PascalCase → snake_case

• DefaultCascadeMode: applies to validators that don't override GlobalCascadeMode themselves.
• DisplayNameResolver: transforms the text shown in {PropertyName} inside messages — does NOT change the key used in ValidationResult.Errors.
• PropertyNameResolver: transforms the actual key used in ValidationResult.Errors/Failures.

Reusable Custom Rules

For a custom rule you want to unit-test in isolation or share across validators, implement IPropertyValidator<TProperty> (or extend the PropertyValidator<TProperty> convenience base) instead of an inline .Must(...) predicate:

public class EvenNumberValidator : IPropertyValidator<int>
{
    public bool IsValid(int value) => value % 2 == 0;
    public IReadOnlyDictionary<string, string> Messages { get; } = new Dictionary<string, string>
    {
        ["en"] = "The {PropertyName} field must be an even number.",
        ["es"] = "El campo {PropertyName} debe ser un número par."
    };
}

RuleFor(x => x.Age).SetPropertyValidator(new EvenNumberValidator());

.SetPropertyValidator(...) integrates like every other rule — .WithSeverity(...), .WithErrorCode(...), .When(...), .Unless(...), and .WithMessage(...) all work on it.

CascadeMode

Stop validation after the first property failure across all properties:

public class MyValidator : AbstractValidator<MyDto>
{
    protected override CascadeMode GlobalCascadeMode => CascadeMode.StopOnFirstFailure;

    public MyValidator()
    {
        RuleFor(x => x.Name).NotEmpty();
        RuleFor(x => x.Email).Email(); // Skipped if Name already fails
    }
}

RuleSets

Tag rules with .InRuleSet(...) and restrict a single Validate/ValidateAsync call to only the rule sets you name via IncludeRuleSets(...). Rules with no InRuleSet call carry the implicit tag "default" and are skipped unless "default" is itself included:

public class OrderValidator : AbstractValidator<Order>
{
    public OrderValidator()
    {
        RuleFor(x => x.CustomerName).NotEmpty(); // implicit "default" rule set

        RuleFor(x => x.PaymentMethod)
            .NotEmpty()
            .InRuleSet("checkout");
    }
}

// Runs only rules tagged "checkout"
var result = validator.Validate(order, o => o.IncludeRuleSets("checkout"));

// Runs every rule regardless of tag (same as always)
var result = validator.Validate(order);

InRuleSet(...) is additive — call it multiple times (or pass multiple names) to tag a rule with more than one rule set. ValidateAsync supports the same Action<ValidationOptions> overload.

Nested Validators

RuleFor(x => x.Address).SetValidator(new AddressValidator());

Resolve the nested validator from DI instead of constructing it yourself with .InjectValidator<T, TProperty>(IServiceProvider) — useful when nested validators are registered via AddValidationsFromAssembly and the root validator receives an IServiceProvider:

public class OrderValidator : AbstractValidator<Order>
{
    public OrderValidator(IServiceProvider serviceProvider)
    {
        RuleFor(x => x.Address).InjectValidator<Order, Address>(serviceProvider);
    }
}

Throws InvalidOperationException if no IValidator<TProperty> is registered, or if the registered implementation isn't an AbstractValidator<TProperty>.

Collection Validation

RuleForEach(x => x.Tags).NotEmpty().MinimumLength(2);

DI Registration

// Register all validators from an assembly
services.AddValidationsFromAssembly(typeof(CreateUserValidator).Assembly);

// Or register individually
services.AddScoped<IValidator<CreateUserDto>, CreateUserValidator>();

Links

• GitHub Repository
• NuGet Package

Donations

If Vali-Validation is useful to you, consider supporting its development:

• Latin America — MercadoPago
• International — PayPal

License

Apache License 2.0

Contributions

Issues and pull requests are welcome on GitHub.