Crafting Custom Model Validation in ASP.NET Core with DataAnnotations

Web forms remain the workhorses of business applications, and nowhere is robust input validation more essential than when accepting data from users scattered across regions like Sydney, Perth, and far-flung mining sites in the Pilbara. A postcode field, a phone number, or a tax file number all demand rules that go beyond "non-empty." While ASP.NET Core ships with a generous set of built-in DataAnnotations, real projects almost always need to enforce business logic that no out-of-the-box attribute can satisfy.

This piece walks through extending the validation framework with your own ValidationAttribute classes, leveraging IValidatableObject for cross-field checks, and wiring everything up so ModelState behaves the way you expect. Along the way, we will reference Australian standards, idioms, and a few quirks of local data so the examples feel grounded rather than generic.

Understanding the Building Blocks

DataAnnotations in ASP.NET Core are attributes that decorate model properties. The framework reflects over them during model binding and invokes their IsValid methods, collecting failures into ModelState. The base class System.ComponentModel.DataAnnotations.ValidationAttribute exposes two overloads of IsValid: one that receives just the value, and another that takes a ValidationContext giving access to the display name, model metadata, and dependency injection via GetService.

For self-contained rules on a single property, deriving from ValidationAttribute and overriding IsValid(object value, ValidationContext context) is the cleanest path. You return ValidationResult.Success when the rule passes, or a new ValidationResult with a localised error message when it does not. The ValidationContext lets you tap into services, so you can query a database, call an external API, or look up an ABN register without resorting to static state.

When rules involve two or more properties on the same model — comparing a start date to an end date, or ensuring a discount percentage never exceeds a partner tier limit — the IValidatableObject interface is a better fit. Its single Validate method receives a ValidationContext and yields an IEnumerable<ValidationResult>, letting you push several failures at once. The runtime calls this method after the attribute pipeline, so it sees a model whose primitive annotations have already been evaluated.

When Built-ins Fall Short

The shipped attributes cover email, URL, phone, range, string length, and credit card formatting, which is more than enough for prototypes. Yet the moment a Melbourne fintech asks for Australian Business Number checks or a healthcare provider in Adelaide insists on validating a Medicare card number against the checksum algorithm, the toolbox feels thin. The [Phone] attribute, for instance, accepts almost any string with at least seven digits, so it will happily accept international numbers that fail local conventions like the 04XX XXX XXX mobile pattern.

Another common snag is conditional validation. Suppose a survey field labelled "Other comments" should be required only when the corresponding multiple-choice answer is "Something else." DataAnnotations have no first-class notion of conditionality. You can fake it by making the property nullable and writing the rule inside a custom attribute or the Validate method, but that mixes concerns and makes the model harder to read.

Time zones introduce yet another wrinkle. A scheduler for a Brisbane dental clinic may accept appointments expressed in Australian Eastern Standard Time, but the server hosting the app in an AWS Sydney region returns UTC. An attribute that compares a stored value with DateTime.Now will fail every time the user is on a daylight-saving boundary. Local-aware validation needs the context of the request, not just the property value.

Writing Your First Custom ValidationAttribute

Start by creating a class that derives from ValidationAttribute and override IsValid. For an Australian postcode, the rule is straightforward: exactly four digits, with the first digit not zero. The attribute can be sealed to prevent further inheritance and decorated with [AttributeUsage(AttributeTargets.Property)] to clarify intent.

[AttributeUsage(AttributeTargets.Property)]
public sealed class AustralianPostcodeAttribute : ValidationAttribute
{
    public AustralianPostcodeAttribute() 
        : base("The {0} field must be a valid Australian postcode.") { }

    public override bool IsValid(object value)
    {
        if (value is null) return true;
        if (value is not string text) return false;
        return Regex.IsMatch(text, "^[1-9][0-9]{3}$");
    }
}

The constructor passes a default message template through to the base. The {0} placeholder is replaced by the property display name when the error is rendered. Returning true for null is deliberate: combine the attribute with [Required] when the field must be present.

To make the message user-friendly without hard-coding English, override FormatErrorMessage and pull from IStringLocalizer or a resource file. Registering the attribute with the dependency injection container is not necessary because attribute instances are created by the runtime, but you can still reach services by switching to the ValidationContext overload and calling validationContext.GetService<>().

Cross-Property Checks with IValidatableObject

Models for e-commerce orders often need rules that touch several fields. Imagine a B2B portal in Parramatta where invoices over a certain dollar threshold require a purchase order number. Implementing this as a single attribute on PurchaseOrder would not stop someone from setting that property to null while the Amount exceeds the limit.

public class Invoice : IValidatableObject
{
    [Required]
    public decimal Amount { get; set; }

    public string? PurchaseOrder { get; set; }

    public IEnumerable<ValidationResult> Validate(ValidationContext ctx)
    {
        if (Amount > 10_000m && string.IsNullOrWhiteSpace(PurchaseOrder))
        {
            yield return new ValidationResult(
                "A purchase order number is required for invoices over $10,000.",
                new[] { nameof(PurchaseOrder) });
        }
    }
}

Notice the second argument to ValidationResult: the member names array. When MVC binds this model, it uses the names to attach errors to the correct fields in the rendered HTML, so the user sees the failure next to the purchase order input rather than at the top of the form. The IEnumerable contract lets you push many failures in a single pass, which is valuable for multi-step forms where you want to show every problem at once instead of forcing the user to fix them one by one.

Local Contexts and Real-World Integration

Australian projects live under regulatory expectations that off-the-shelf validators ignore. Validating a Tax File Number, for example, requires a weighted checksum that no built-in attribute implements. The algorithm weights each digit by 1, 4, 3, 7, 5, 8, 6, 9, 10 and checks divisibility by eleven. Such a rule belongs in a custom attribute that documents the source of the algorithm and explicitly warns against storing the TFN unencrypted.

Regional phone formats also deserve attention. Mobile numbers start with 04 and have ten digits, while landline numbers in Hobart, Darwin, or regional Western Australia follow varied area codes. A pragmatic custom attribute normalises input by stripping spaces and parentheses, then matches against a curated regex per state. Pair it with a server-side lookup against the Australian Communications and Media Authority numbering plan when accuracy matters more than latency.

Conference attendees exploring stream-based architectures will appreciate how validation logic can be reused across HTTP endpoints and background workers. The same attribute applied to a DTO consumed by a Kafka topic in Stream Processing with Azure Stream Analytics and C# keeps ingestion pipelines consistent with web forms. This shared definition reduces drift and lets a single change propagate to every layer that touches the schema.

Testing and Avoiding Common Pitfalls

Unit-testing custom attributes is refreshingly direct because IsValid is essentially a pure function. Create an instance of the attribute, pass in sample values, and assert the result. For rules that depend on ValidationContext, build one manually using ValidationContext.CreateInstance and supply a service provider for any dependencies. Property-level tests should cover happy paths, boundary conditions, null inputs, and locale-specific edge cases such as leading zeros in postcodes or Unicode characters in names.

Watch out for three recurring traps. First, throwing exceptions from IsValid will short-circuit the pipeline and surface as a 500 error rather than a validation message; always return ValidationResult instead. Second, avoid putting database writes inside an attribute; validation should be idempotent and side-effect free because the same model can be validated multiple times per request. Third, remember that client-side unobtrusive validation only works for attributes that ship matching adapters; custom attributes need a corresponding client-side function or an IClientModelValidator implementation if you want jQuery validate to enforce them in the browser.

Finally, profile the cost. An attribute that calls an external API on every keystroke through remote validation can quickly exhaust rate limits and balloon response times. Cache expensive lookups, prefer asynchronous methods where the framework allows them, and reserve round-trip checks for genuinely volatile data. Done well, custom DataAnnotations become a reusable, expressive vocabulary for your domain that keeps controllers thin, models honest, and end-users in Hobart, Sydney, and Broome free from confusing error messages.