Creating Custom Data Annotations in ASP.NET Core

ASP.NET Core includes a practical set of validation attributes for common rules such as [Required], [StringLength], [Range], and [EmailAddress]. Those attributes cover many forms, yet production applications often need rules that reflect a particular business process. A customer reference may need a specific prefix, an Australian Business Number may need a checksum, or two dates may need to remain within an approved booking window.

A custom data annotation packages that rule into a reusable validation component. The result is a model that describes both its data shape and its basic business constraints, while controllers and Razor Pages can rely on ModelState to receive consistent validation results. The same approach works for MVC views, Web API endpoints, and many service-layer workflows.

For teams working across Sydney, Melbourne, Brisbane, or regional offices, consistent validation is especially useful when web portals, mobile clients, and internal systems share the same API. A rule implemented once can prevent different interpretations between a customer-facing form and a back-office workflow, whether the application is used during a busy arvo or by staff working across Australian time zones.

Why built-in validation may not be enough

Built-in attributes are ideal when the rule maps directly to a general-purpose constraint. [Required] can ensure a value exists, [Range] can restrict a number, and [RegularExpression] can check a simple pattern. Problems arise when the requirement carries domain meaning. For example, a claim may be valid only when its settlement date follows its incident date, or a supplier code may have a prefix determined by the supplier category.

Putting these checks directly inside a controller tends to produce duplication. One endpoint might reject invalid data while another accepts it, and a Razor view may display a different message from an API client. Keeping the rule in a validation attribute gives the model a single, discoverable source of truth. It also makes the constraint easier to test without running the entire HTTP pipeline.

Validation should still be placed at the right level. A format check belongs comfortably in an attribute, but a rule requiring a database lookup, a remote service, or a transaction usually belongs in an application service. Attributes are excellent for deterministic model validation; they should not become a hidden replacement for business workflows.

Designing a reusable validation attribute

A custom validator normally derives from ValidationAttribute and overrides IsValid. The method receives the property value and can return ValidationResult.Success when the value passes. When it fails, return a ValidationResult with a clear message and, where appropriate, the member name associated with the error.

The following attribute validates an Australian-style business identifier by checking that it contains exactly 11 digits and satisfies the ABN weighted checksum. It accepts spaces because users commonly enter identifiers in grouped form on Australian forms.

using System.ComponentModel.DataAnnotations;

public sealed class AustralianBusinessNumberAttribute
    : ValidationAttribute
{
    private static readonly int[] Weights =
        { 10, 1, 3, 5, 7, 9, 11, 13, 15, 17, 19 };

    protected override ValidationResult? IsValid(
        object? value,
        ValidationContext validationContext)
    {
        if (value is null || string.IsNullOrWhiteSpace(value.ToString()))
            return ValidationResult.Success;

        var digits = value.ToString()!
            .Replace(" ", string.Empty)
            .Replace("-", string.Empty);

        if (digits.Length != 11 || !digits.All(char.IsDigit))
            return new ValidationResult(
                "Enter an 11-digit Australian Business Number.");

        var numbers = digits.Select(c => c - '0').ToArray();
        numbers[0]--;

        var remainder = numbers
            .Zip(Weights, (number, weight) => number * weight)
            .Sum() % 89;

        return remainder == 0
            ? ValidationResult.Success
            : new ValidationResult("Enter a valid Australian Business Number.");
    }
}

Returning success for a missing value is intentional. The [Required] attribute should decide whether the field is compulsory, while this attribute decides whether a supplied value has the correct structure and checksum. Separating those responsibilities prevents confusing error messages and lets the same validator work for optional supplier records.

Applying the attribute to a model

Once the attribute exists, apply it to a view model or request contract. A view model is often preferable to placing presentation-specific rules on an entity that is shared with persistence. This keeps validation aligned with the input being accepted by a particular endpoint.

public sealed class SupplierRegistrationModel
{
    [Required]
    [Display(Name = "Business name")]
    public string BusinessName { get; set; } = string.Empty;

    [Required]
    [AustralianBusinessNumber]
    [Display(Name = "ABN")]
    public string Abn { get; set; } = string.Empty;
}

An MVC action can then rely on automatic model binding and inspect ModelState.IsValid.

[HttpPost]
public IActionResult Register(SupplierRegistrationModel model)
{
    if (!ModelState.IsValid)
        return View(model);

    // Continue with the registration workflow.
    return RedirectToAction(nameof(Complete));
}

In an API using [ApiController], invalid model state normally produces an automatic HTTP 400 response. The response includes validation details that frontend developers can map to form fields. This behaviour is useful for teams building a Vue, React, or mobile client for an Australian customer portal because the server remains the final authority, even if client-side checks are also present.

Producing useful validation messages

A validation message should explain the correction without exposing implementation details. “The checksum returned remainder 17” is technically accurate but unhelpful to a person entering a supplier identifier. Messages should also use the vocabulary familiar to the application’s users, such as “ABN” rather than a generic phrase like “business number” when that distinction matters.

For reusable libraries, support a custom error message through the base class. ValidationAttribute provides an ErrorMessage property, so consumers can write [AustralianBusinessNumber(ErrorMessage = "Please check the supplier ABN.")]. A resource-based error message is a better option when an application supports multiple languages or must align messages with an established content system.

The attribute should be defensive around null values, unexpected types, and whitespace. It should not throw an exception simply because a client sent malformed input. Exceptions indicate a programming or infrastructure problem; ordinary invalid input should become a normal validation error. This distinction matters for public APIs, where malformed requests are routine rather than exceptional.

Handling dependent properties and services

Some rules involve more than one property. For example, an end date must follow a start date, or a discount code may be available only for a selected membership level. A property-level attribute is awkward when it needs to compare sibling values. In that situation, implement IValidatableObject on the model or use a class-level validation attribute.

public sealed class BookingModel : IValidatableObject
{
    [Required]
    public DateTime? StartDate { get; set; }

    [Required]
    public DateTime? EndDate { get; set; }

    public IEnumerable<ValidationResult> Validate(
        ValidationContext validationContext)
    {
        if (StartDate.HasValue && EndDate.HasValue &&
            EndDate.Value.Date < StartDate.Value.Date)
        {
            yield return new ValidationResult(
                "The end date must be on or after the start date.",
                new[] { nameof(StartDate), nameof(EndDate) });
        }
    }
}

ValidationContext can expose services through dependency injection, but service-dependent validation deserves caution. A validator that queries a database for every property can create slow, surprising behaviour and make unit tests harder to isolate. For a rule such as checking whether a supplier is already registered, validate the shape with an attribute and perform the uniqueness check in an application service.

That split is valuable in Australian enterprise systems, where an API may integrate with accounting platforms, state-based workflows, or government-facing records. Local business rules can change independently of a form’s basic data constraints, so keeping external decisions in a service makes the application easier to maintain and audit.

Connecting server and browser validation

Server-side validation is mandatory because requests can bypass browser scripts. Client-side validation is still valuable because it gives immediate feedback. ASP.NET Core’s unobtrusive validation system can render client rules for built-in attributes, but a custom ValidationAttribute does not automatically generate JavaScript that reproduces every custom algorithm.

For simple rules, implement an IClientModelValidator or register an adapter so the attribute emits a data-val-* rule. The browser script can then perform the lightweight check, while the server runs the authoritative implementation. Avoid duplicating complicated logic in JavaScript if it is likely to drift from the C# version.

The response format also matters. MVC applications typically redisplay the form with field-level messages, while APIs return a structured validation problem response. Consistent property names and messages make it easier for clients to render errors. This is particularly helpful when a Sydney-based frontend team and a Perth-based backend team release on different schedules and need a stable contract between them.

Teams preparing for a technical event or reviewing modern .NET practices can compare patterns with material from the conference programme, where cloud, web development, data, and Microsoft technologies are common areas of discussion. The same design principles apply whether an application runs on a local development machine or in Azure.

Choosing an approach and testing it

The right technique depends on the scope of the rule. A property attribute is concise and reusable for one value. IValidatableObject is clearer when several fields participate in a constraint. A service is the safer home for checks involving persistence, external systems, authorisation, or a changing business policy.

Unit tests should cover valid values, invalid values, nulls, whitespace, formatting variations, and boundary cases. For the ABN example, test grouped and ungrouped input, an incorrect first digit, a wrong checksum, and an 11-character value containing letters. Integration tests should then confirm that MVC or API model binding turns failures into the expected ModelState entries or HTTP response.

A well-structured validation strategy uses these options together rather than forcing every rule into an annotation. Keep simple input constraints close to the model, keep cross-field comparisons explicit, and reserve services for decisions that require context. That approach produces predictable ASP.NET Core applications for Australian businesses, from small local suppliers to large cloud-hosted platforms serving customers nationwide.