ASP.NET - ASP.NET Core Model Metadata and Display Conventions

Introduction

In ASP.NET Core MVC and Razor-based applications, a model represents the data that an application works with. For example, a Student model might contain properties such as StudentId, FirstName, LastName, Email, and DateOfBirth. While these property names are useful to developers, they are not always suitable for displaying directly to users. A web application may need to show First Name instead of FirstName, provide a meaningful description, specify a placeholder, control the display order, or determine whether a property should appear in an editing interface.

This is where model metadata becomes important. Model metadata is information that ASP.NET Core associates with a model type, property, or parameter. ASP.NET Core's ModelMetadata represents metadata for these elements and is used by MVC's model binding, validation, and UI-related systems.

What Is Model Metadata?

Model metadata is additional information about a model beyond its actual data value and data type. Consider the following model:

public class Student
{
    public int StudentId { get; set; }

    public string FirstName { get; set; }

    public string LastName { get; set; }

    public DateTime DateOfBirth { get; set; }
}

ASP.NET Core knows that StudentId is an integer, FirstName and LastName are strings, and DateOfBirth is a date. However, the framework can also associate presentation-related information with these properties.

For example:

using System.ComponentModel.DataAnnotations;

public class Student
{
    public int StudentId { get; set; }

    [Display(Name = "First Name")]
    public string FirstName { get; set; }

    [Display(Name = "Last Name")]
    public string LastName { get; set; }

    [Display(Name = "Date of Birth")]
    public DateTime DateOfBirth { get; set; }
}

Here, the Display attributes provide metadata that can influence how the properties are presented in the user interface. Microsoft documentation specifically describes the DisplayAttribute.Name value as a value used for displaying a property in the UI. 

Instead of displaying:

FirstName
LastName
DateOfBirth

a view can display:

First Name
Last Name
Date of Birth

This separates the internal programming name from the name presented to the user.

DisplayAttribute

The DisplayAttribute from System.ComponentModel.DataAnnotations is one of the most useful mechanisms for defining display metadata.

A simple example is:

[Display(Name = "Student Name")]
public string FullName { get; set; }

The property remains FullName in C#, but the UI can use Student Name.

The attribute provides several useful properties, including Name, Description, Prompt, and Order. 

Display Name

The Name property controls the user-friendly name associated with a model property.

[Display(Name = "Email Address")]
public string Email { get; set; }

The application can use Email Address as the field label instead of the property name Email.

This is particularly useful when property names follow programming conventions that are not necessarily appropriate for end users.

For example:

[Display(Name = "Emergency Contact Number")]
public string EmergencyContactNumber { get; set; }

The C# property can remain descriptive and consistent with coding conventions while the UI presents a more readable label.

Display Descriptions

Metadata can also provide descriptive information about a field.

[Display(
    Name = "Email Address",
    Description = "Enter the student's primary email address."
)]
public string Email { get; set; }

The Description property is intended to provide descriptive UI information and can be used, for example, as explanatory text or a tooltip depending on the UI implementation. 

This can make forms easier to understand without putting explanatory text directly into the model's Razor view.

Prompt and Placeholder Information

The Prompt property provides text that can be used as a prompt or watermark in an input control.

[Display(
    Name = "Student Name",
    Prompt = "Enter student name"
)]
public string StudentName { get; set; }

The resulting input can use:

Enter student name

as its placeholder or prompt, depending on how the view and tag helpers render the metadata. Microsoft documents Prompt specifically as information used to set the watermark for prompts in the UI. 

This is useful when users need guidance about what information should be entered.

Controlling Display Order

Metadata can also influence the order in which properties are presented.

public class Student
{
    [Display(Name = "Student ID", Order = 1)]
    public int StudentId { get; set; }

    [Display(Name = "First Name", Order = 2)]
    public string FirstName { get; set; }

    [Display(Name = "Last Name", Order = 3)]
    public string LastName { get; set; }

    [Display(Name = "Email Address", Order = 4)]
    public string Email { get; set; }
}

The Order property provides an ordering weight. Display-oriented components can use these values when determining the presentation order of fields. Microsoft specifies that columns are sorted according to increasing order values when the presentation layer uses this metadata. 

This can be useful when the order in which properties are declared in a model does not match the desired order of fields in a form.

Display Format Metadata

ASP.NET Core also supports metadata related to how values should be displayed.

For example:

[DisplayFormat(DataFormatString = "{0:dd-MM-yyyy}")]
public DateTime DateOfBirth { get; set; }

The property continues to contain a DateTime value, but the display layer can use the specified format when rendering it.

Another example could be:

[DisplayFormat(DataFormatString = "{0:C}")]
public decimal Fee { get; set; }

This indicates that the value should be displayed using a currency-oriented format when the relevant display helper uses the metadata.

ASP.NET Core's DisplayMetadata includes information such as display format strings, data type names, null display text, ordering, placeholder information, and whether a property should be shown for display or editing. 

DataType Metadata

The DataType attribute can provide additional information about the intended type or presentation of a value.

For example:

[DataType(DataType.Date)]
public DateTime DateOfBirth { get; set; }

This communicates that the property should be treated as a date for presentation purposes.

Microsoft's ASP.NET Core MVC tutorial demonstrates the combination of Display and DataType attributes. Display changes the field's displayed name, while DataType supplies information about how the data should be treated for display. 

ShowForDisplay and ShowForEdit

Model metadata can also determine whether a property is appropriate for display or editing.

For example, DisplayMetadata contains ShowForDisplay and ShowForEdit properties. These allow presentation systems to determine whether a model value should be included in display or editing scenarios. 

This distinction is important because an application may want to show information to a user without allowing that information to be edited.

For instance, a system-generated identifier might be displayed on a details page but excluded from an edit form.

Model Metadata and Model Binding

Model metadata is not limited to controlling the visual appearance of forms. ASP.NET Core also uses metadata as part of model binding and validation behavior.

Microsoft's documentation states that model binding and validation behavior is driven by ModelMetadata. ASP.NET Core allows developers to customize this metadata through MvcOptions.ModelMetadataDetailsProviders. 

For example, an application can add metadata providers that change how certain types participate in model binding or validation.

A simplified configuration can look like this:

builder.Services
    .AddControllersWithViews()
    .AddMvcOptions(options =>
    {
        // Model metadata providers can be added here.
    });

This provides a way to customize metadata behavior at the framework level rather than adding attributes to every individual model property.

Metadata Providers

ASP.NET Core has a metadata system that builds ModelMetadata from various sources. These sources can include attributes applied to model classes and properties as well as framework conventions and metadata providers.

Developers can extend this system when application-wide behavior is required.

For example, if an organization wants every property of a particular type to follow a certain presentation convention, creating a metadata provider can be more appropriate than repeatedly adding attributes to hundreds of model properties.

This approach is especially useful in large applications where consistency is important.

Conventions

A convention is a predefined rule that allows the framework to determine behavior without requiring explicit configuration for every individual property.

For example, a property called:

FirstName

can be presented differently depending on the UI component being used and the metadata available to it.

Explicit metadata can override or supplement these default behaviors.

This gives developers two approaches:

Convention-based behavior
        |
        v
Framework determines appropriate metadata
        |
        v
Explicit metadata
        |
        v
Developer specifies desired presentation

The result is less repetitive code while still allowing precise customization when necessary.

Customizing Metadata

For advanced applications, developers can create custom metadata providers.

A custom provider can be used when metadata needs to be generated dynamically or applied consistently across many models.

ASP.NET Core exposes metadata-related extension points through MVC configuration. For example, MvcOptions.ModelMetadataDetailsProviders allows additional metadata providers to be registered. Microsoft specifically documents this mechanism for modifying model metadata behavior. (Microsoft Learn)

This can be useful for requirements such as:

• Applying common display conventions.

• Modifying metadata for a specific type.

• Controlling whether certain properties participate in validation.

• Controlling whether certain types participate in model binding.

• Applying organization-wide UI conventions.

Example of a Complete Model

Consider an employee registration model:

using System.ComponentModel.DataAnnotations;

public class Employee
{
    [Display(Name = "Employee ID", Order = 1)]
    public int EmployeeId { get; set; }

    [Display(
        Name = "Full Name",
        Prompt = "Enter employee name",
        Description = "Enter the employee's complete name.",
        Order = 2
    )]
    public string FullName { get; set; }

    [Display(
        Name = "Email Address",
        Prompt = "[email protected]",
        Order = 3
    )]
    public string Email { get; set; }

    [Display(Name = "Joining Date", Order = 4)]
    [DataType(DataType.Date)]
    public DateTime JoiningDate { get; set; }
}

This model contains both data and presentation metadata.

The actual data properties remain:

EmployeeId
FullName
Email
JoiningDate

But the UI can use:

Employee ID
Full Name
Email Address
Joining Date

It can also use prompts, descriptions, ordering information, and date-specific presentation behavior.

Why Model Metadata Is Important

Model metadata provides a clean separation between the data model and the way that model is presented or interpreted by ASP.NET Core.

Without metadata, developers may repeatedly write labels and formatting rules directly inside Razor views:

<label>Full Name</label>

With metadata, the model can provide this information:

[Display(Name = "Full Name")]
public string FullName { get; set; }

The view can then use framework helpers that understand the metadata.

This approach improves consistency and reduces duplication. It is particularly valuable when the same model is displayed in multiple views.

Model Metadata vs. Validation

It is important to distinguish display metadata from validation metadata.

For example:

[Display(Name = "Email Address")]
[Required]
[EmailAddress]
public string Email { get; set; }

Here:

Display(Name = "Email Address")

provides presentation information.

Required

defines a validation requirement.

EmailAddress

defines an email-format validation requirement.

All of these attributes can be associated with the same property, but they serve different purposes.

Advantages of Model Metadata

Model metadata offers several important advantages.

Improved user interfaces: Developers can provide readable labels, descriptions, prompts, formatting information, and display ordering.

Less duplication: Presentation information can be defined once rather than repeated throughout multiple views.

Better maintainability: If a field's display name changes, the metadata can be changed in the model instead of searching through numerous views.

Consistency: Multiple pages that use the same model can follow the same display conventions.

Centralized configuration: Advanced metadata providers can apply rules across an application.

Better separation of concerns: Models can provide structured information about how their properties should be interpreted, while views remain responsible for rendering that information.

Conclusion

ASP.NET Core Model Metadata and Display Conventions provide a mechanism for describing how models and their properties should be interpreted by MVC and UI components. ModelMetadata represents metadata associated with model types, properties, and parameters, while attributes such as Display, DisplayFormat, and DataType allow developers to supply useful presentation information. 

The most common use is making model properties more user-friendly. A property such as DateOfBirth can be given the display name Date of Birth, a prompt can guide users during data entry, a description can provide additional information, and an order value can influence where the field appears. At a deeper level, metadata also participates in model binding and validation behavior, making it an important part of ASP.NET Core's MVC infrastructure.

Understanding model metadata is therefore useful not only for creating cleaner forms but also for building maintainable ASP.NET Core applications in which presentation rules and framework behavior can be controlled systematically.