Custom Validation Messages in .NET 11 With DataAnnotations

Use this customization only when a consistent response format is useful for your API clients. If your application already relies on ASP.NET Core's standard validation response, changing the format may require updates to existing clients.

Creating a Custom Validation Attribute

Built-in attributes cover many common rules, but business applications often require additional validation.

Suppose a registration form accepts a username that must contain only letters, digits, and underscores. You can implement a reusable attribute by inheriting from ValidationAttribute.

using System.ComponentModel.DataAnnotations;
using System.Text.RegularExpressions;

public sealed class UsernameAttribute : ValidationAttribute
{
    private static readonly Regex UsernamePattern =
        new(@"^[A-Za-z0-9_]+$", RegexOptions.Compiled);

    public override bool IsValid(object? value)
    {
        if (value is null)
        {
            return true;
        }

        if (value is not string username)
        {
            return false;
        }

        return UsernamePattern.IsMatch(username);
    }
}

The attribute checks the supplied value against a regular expression.

Returning true for null is intentional. A custom format attribute generally should not duplicate the responsibility of [Required]. If the property is mandatory, apply both attributes.

Use the custom attribute in a model:

public class CreateAccountRequest
{
    [Required(ErrorMessage = "Please choose a username.")]
    [Username(ErrorMessage =
        "Your username can contain only letters, numbers, and underscores.")]
    public string Username { get; set; } = string.Empty;
}

The two attributes handle different rules:

• [Required] checks whether the user supplied a value.

• [Username] checks whether the supplied value follows the required format.

Separating these responsibilities makes validation easier to maintain and reuse.

For a real application, also consider username length, reserved names, case sensitivity, and database uniqueness. A regular expression alone does not guarantee that a username can be registered successfully.

When custom attributes are appropriate

A custom validation attribute is useful when a rule is:

• Reused across several models.

• Independent of external services or database state.

• Easy to express as a deterministic check.

• Expected to produce a consistent validation message.

Rules that require database queries, remote service calls, or access to other application services are often better implemented in an application service or dedicated validation layer.

For example, checking whether an email address already exists in the database is not the same as checking whether its format is valid. The format can be validated locally, while uniqueness should be enforced through appropriate application and database logic.

Using ValidationAttribute for More Detailed Messages

Sometimes a custom attribute needs to generate a message based on the value or configuration.

You can override FormatErrorMessage to control how the message is formatted.

using System.ComponentModel.DataAnnotations;

public sealed class MinimumOrderQuantityAttribute
    : ValidationAttribute
{
    public int MinimumQuantity { get; }

    public MinimumOrderQuantityAttribute(int minimumQuantity)
    {
        if (minimumQuantity < 1)
        {
            throw new ArgumentOutOfRangeException(
                nameof(minimumQuantity));
        }

        MinimumQuantity = minimumQuantity;
    }

    public override bool IsValid(object? value)
    {
        if (value is null)
        {
            return true;
        }

        return value is int quantity &&
               quantity >= MinimumQuantity;
    }

    public override string FormatErrorMessage(string name)
    {
        return $"{name} must be at least {MinimumQuantity}.";
    }
}

Apply the attribute to a request model:

public class OrderRequest
{
    [MinimumOrderQuantity(5)]
    public int Quantity { get; set; }
}

When validation fails, the message can include the configured minimum quantity.

This pattern is useful when the same rule applies to different properties but the required threshold varies.

For example, a product might require a minimum order of five units, while another product requires a minimum order of ten. The attribute can express the numeric requirement, although rules that depend on the selected product may be more appropriately handled by application-level validation.

Localizing Validation Messages

Applications used in multiple countries may need validation messages in different languages.

Hardcoding English messages in every attribute makes localization more difficult. DataAnnotations support resource-based error messages through ErrorMessageResourceType and ErrorMessageResourceName.

For example, suppose a resource class named ValidationMessages contains a resource entry named NameRequired.

using System.ComponentModel.DataAnnotations;

public class CustomerRequest
{
    [Required(
        ErrorMessageResourceType = typeof(ValidationMessages),
        ErrorMessageResourceName = nameof(ValidationMessages.NameRequired))]
    public string Name { get; set; } = string.Empty;
}

The resource class represents generated resource accessors for a .resx file. In a real project, create the resource file and add the corresponding entry before using this example.

You can provide translated resource files for supported cultures. ASP.NET Core localization middleware and request-culture configuration can then determine which culture applies to the request.

This keeps validation messages separate from business logic and makes it easier to maintain translations.

When localizing messages, pay attention to grammar and placeholder ordering. A sentence structure that works in English may not work in another language if the property name and numeric values appear in different positions.

Common Mistakes to Avoid

Assuming Required rejects every invalid value

[Required] checks whether a value is present. For strings, it also rejects empty or whitespace-only values by default. It does not validate email formats, numeric ranges, or business-specific rules.

Combine attributes when a property has multiple requirements.

Duplicating validation rules

If the same rule appears in several models, the messages and permitted values can become inconsistent.

Use a shared custom attribute or a centralized validation component when the rule is genuinely reusable. Avoid building abstractions for rules that appear only once and are unlikely to be reused.

Treating client-side validation as sufficient

Browser validation improves usability, but clients can bypass it. Validate incoming requests on the server before processing them.

For rules that protect data integrity, enforce the relevant constraints in the application and, where appropriate, the database as well.

Performing database queries inside validation attributes

A validation attribute should generally remain predictable and lightweight. Database access introduces dependencies, asynchronous execution concerns, and additional complexity.

Use an application service or a dedicated validator for rules that require external data.

Changing API validation responses without checking clients

Frontend applications may depend on the default ASP.NET Core validation response. Changing its structure can break existing integrations.

Document the response contract and update API tests whenever the format changes.

Best Practices for Production Applications

Use these practices to keep validation behavior consistent and maintainable:

1. Write messages that explain the expected input rather than exposing framework terminology.

2. Keep format validation separate from required-field validation when the rules have different responsibilities.

3. Use display names and supported placeholders to reduce repeated message text.

4. Create custom attributes for reusable, local validation rules.

5. Keep database-dependent and cross-service validation in an appropriate application layer.

6. Validate requests on the server even when the user interface performs client-side validation.

7. Standardize API error responses when multiple clients consume the same API.

8. Add tests for valid input, invalid input, boundary values, and missing values.

9. Store translatable messages in resources when localization is required.

10. Review error messages to ensure they do not expose internal implementation details or sensitive information.

Advantages and disadvantages

Choose the simplest approach that meets the application's requirements. Built-in attributes with custom messages are enough for many forms. More advanced techniques should solve a real maintenance or integration problem.

Summary

DataAnnotations provide a straightforward way to validate .NET models, but the default error messages are not always suitable for application users.

Setting ErrorMessage values makes common validation rules easier to understand. Display names and placeholders help maintain consistency, while custom attributes support reusable rules that are not covered by built-in validation attributes.

For ASP.NET Core APIs, the validation response can also be customized to provide a consistent structure for client applications. Resource-based messages are useful when an application supports multiple languages.

The key is to keep validation understandable and focused. Use DataAnnotations for local model rules, place database-dependent checks in the appropriate application layer, and always validate untrusted input on the server.