Column definitions

Tables include a collection of columns that represent the data that can be included within each record. Developers need to understand the different types of columns and how to work with them.


Unsure about entity vs. table? See Developers: Understand terminology in Microsoft Dataverse.

More information: Introduction to table columns

Columns names

Like tables, each column has a unique name defined when it is created. This name is presented in several ways:

Name Description
SchemaName Typically, a Pascal cased version of the logical name. i.e. AccountNumber
LogicalName All lower-case name. i.e. accountnumber

When you create a custom column, the name you choose will be prepended with the customization prefix value of the solution publisher associated with the solution that the column was created within.

You cannot change the names of a column after it is created.

Each column also has two properties that can display localized values. These are the values that are used to refer to the columns in an app.

Name Description
DisplayName Typically, the same as the schema name, but can include spaces. i.e. Account Number
Description A short sentence describing the column or providing guidance to the user. i.e. Type an ID number or code for the account to quickly search and identify the account in system views.
In model-driven apps, this information will appear when users hover over the column in a form.

These are the localizable values that are used to refer to the columns in an app. These values can be changed at any time. To add or edit localized values see Microsoft Dataverse Customization Guide: Translate customized table and column text into other languages.

Column types

The AttributeTypeName property describes the type of a column. This property contains a value of type AttributeTypeDisplayName which provides a label for each the different types of columns that exist.


Don't be confused by the AttributeType property. The values in this older property are mostly aligned with AttributeTypeName except that it shows ImageAttributeMetadata and MultiSelectPicklistAttributeMetadata as Virtual. Refer to the AttributeTypeName property rather than the AttributeType property.

In the following table:

  • These types are grouped by category for comparison.
  • For each AttributeTypeDisplayName value, the corresponding .NET assembly AttributeMetadata derived class is included where available. There is not a 1:1 relationship between these types and the AttributeTypeDisplayName label.
  • Those column types that can be created as custom columns include the corresponding label displayed in the UI.
Category AttributeTypeDisplayName/
AttributeMetadata Type
Can Create/
Categorization BooleanType
Two Options
Contains the selected value from Yes/No that usually indicate a true or false value.
More information: Choice
Categorization EntityNameType
No Contains a value that corresponds to a table in the system. For internal use only.
Categorization MultiSelectPicklistType
MultiSelect Option Set
Contains multiple selected values where multiple values can be selected.
More information:
Choices columns
Categorization PicklistType
Option Set
Contains the selected value where one option can be selected.
More information: Choice
Categorization StateType
No Contains the value that describes the status of a table record.
More information: Choice
Categorization StatusType
No Contains the value that describes the reason for the status of a table record.
More information: Choice
Collection CalendarRulesType No Contains a collection of CalendarRules table records.
There are no columns that use this type. When generating a proxy, the code generation tool will create two simulated columns that are not present in the definition. These columns represent a view of the calendar rules records associated in a one-to-many relationship to the table record.
Collection PartyListType No Contains a collection of ActivityParty table records.
More information: ActivityParty table
Date and Time DateTimeType
Date and Time
Contains a date and time value.
All date and time columns support values as early as 1/1/1753 12:00 AM.
File FileType
Contains data to support retrieving binary data for a table record.
More information: File columns
Image ImageType
Contains data to support retrieving image data for a table record.
More information: Entity Images
Managed Property ManagedPropertyType
No Contains data that describe whether the solution component stored in the table record can be customized when included in a managed solution.
More information: Managed Properties
Quantity BigIntType
No Contains a BigInt value. For internal use only.
Quantity DecimalType
Decimal Number
Contains a Decimal value. The Precision property sets the level of precision.
Quantity DoubleType
Floating Point Number
Contains a Double value. The Precision property sets the level of precision.
Quantity IntegerType
Whole Number
Contains an Int value
Quantity MoneyType
Contains a Decimal value. The PrecisionSource property determines where the level of precision is set.
0 : The Precision property
1 : The Organization.PricingDecimalPrecision column
2 : The TransactionCurrency.CurrencyPrecision column in the table record
Reference CustomerType
Contains a reference to either an account or contact table record.
Reference LookupType
Contains a reference to a table record. The logical names of the valid records are usually stored in the Targets property of the column.
Reference OwnerType
No Contains a reference to either a user or team table record.
String MemoType
Multiple Lines of Text
Contains a string value intended to be displayed in a multi-line textbox.
String StringType
Single Line of Text
Contains a string value intended to be displayed in a single-line textbox.
Unique identifier UniqueidentifierType
No Contains a GUID unique identifier value.
Virtual VirtualType No These columns cannot be used in code and can generally be ignored.

Supported operations and form usage for columns

Each column includes boolean properties that describe the kinds of operations it can participate in and how it can be in a form.

Property Description
IsRequiredForForm Whether the column must be included in a form.
IsValidForCreate Whether the column value can be set in a create operation.
IsValidForForm Whether the column can be included as a column in a form.
IsValidForRead Whether the column value can be retrieved.
IsValidForUpdate Whether the column value can be set in an update operation.

If you try to set a value in a create or update operation for a column that is not valid for that operation, the value will be ignored. If you try to retrieve a column that is not valid for read, a null value will be returned.

Column requirement level

The RequiredLevel property is a Boolean managed property that describes if a column value is required.

This property can have the following values set:

Name Value UI Label Description
None 0 Optional No requirements are specified.
SystemRequired 1 System Required The data service requires the column to have a value.
ApplicationRequired 2 Business Required The application requires the column to have a value.
Recommended 3 Business Recommended It is recommended that the column has a value.

Dataverse only enforces the SystemRequired option for columns created by the system. Custom columns cannot be set to use the SystemRequired option. The data service does not return an error when a column with ApplicationRequired applied does not have a value.

Model-driven apps will enforce the ApplicationRequired option and use a different presentation for the Recommended option. Creators of custom clients may use this information to require similar validation or presentation options.

Because this is a managed property, as a publisher of a managed solution you can decide whether consumers of your solution are able to change these settings on columns in your solution.

More information: Managed Properties

Rollup and calculated columns

Calculated and rollup columns free the user from having to manually perform calculations and focus on their work. System administrators can define a column to contain the value of many common calculations without having to work with a developer. Developers can also leverage the platform capabilities to perform these calculations rather than within their own code.

More information:

Column format

The format values for column controls how it is displayed in model-driven apps. Developer of custom apps may use this information to create similar experiences.

Integer formats

Use the Format property with integer columns to display alternate user experiences for this type.

Option Description
None Displays a text box to edit a number value
Duration Displays a drop-down list that contains time intervals. A user can select a value from the list or type an integer value that represents the number of minutes.
TimeZone Displays a drop-down list that contains a list of time zones.
Language Displays a drop-down list that contains a list of languages that have been enabled for the organization. If no other languages have been enabled, the base language will be the only option. The value saved is the LCID value for the language.

String formats

Use the FormatName property with string columns to set values from the StringFormatName Class to control how the string column is formatted.

Name Description
Email The form column will validate the text value as an e-mail address and create a mailto link in the column.
PhoneNumber The form column will contain a link to initiate a phone call by using Skype.
PhoneticGuide For internal use only.
Text The form will display a text box.
TextArea The form will display a text area column.
TickerSymbol The form will display a link that will open to display a quote for the stock ticker symbol.
URL The form will display a link to open the URL.
VersionNumber For internal use only.

Date and time formats

The DateTimeBehavior property to controls the behavior for Date and Time columns. There are three options:

Option Short Description
UserLocal Stores the date and time value as UTC value in the system.
DateOnly Stores the actual date value with the time value as 12:00 AM (00:00:00) in the system.
TimeZoneIndependent Stores the actual date and time values in the system regardless of the user time zone.

Use the Format property control how the value is to be displayed in a model-driven app regardless of the DateTimeBehavior.

Option Description
DateAndTime Display the full date and time
DateOnly Display just the date.

More information: Behavior and format of the date and time columns

Auto-number columns

You can add an auto-number column for any table. Currently, you can add the column programmatically. There is no user interface to add this type of column. More information: Create auto-number columns


Those columns which display a set of options can reference a set of options defined by the column or they can reference a separate set of options that can be shared by more than one column. This is particularly useful when values in one column also apply to other columns. By referencing a common set of options, the options can be maintained in one place. Those choice that can be shared are global choice. Those defined within the column are local choice.

Retrieve options data

The organization service provides request classes you can use to retrieve the options used by a column.

Use the organization service to retrieve options

Each of the columns with options inherit from EnumAttributeMetadata and include an OptionSet Property. This property contains the OptionSetMetadata that includes the options within the Options property.

With the organization service you can use the following messages to retrieve information about choice:

Request Class Description
RetrieveAllOptionSetsRequest Retrieves data about all global choice
RetrieveAttributeRequest Retrieves data about a column including any local choice
RetrieveMetadataChangesRequest Retrieves metadata based on a query that can include local choice
More information: Retrieve and detect changes to metadata
RetrieveOptionSetRequest Retrieves data about a global choice.

More information:

Use the Web API to retrieve choice values

The Web API provides a RESTful style for querying choice values. You can retrieve local or global choice by retrieving the column within a table. The following example returns the OptionSetMetadata for the choice included in the Account.AccountCategoryCode property.

GET <organization url>/api/data/v9.0/EntityDefinitions(LogicalName='account')/Attributes(LogicalName='accountcategorycode')/Microsoft.Dynamics.CRM.PicklistAttributeMetadata?$select=LogicalName&$expand=OptionSet

With the Web API you can also use the RetrieveMetadataChanges Function.

More information: Query table definitions using the Web API > Querying EntityMetadata column

Column mapping

When you create a new table record in the context of an existing table record, you can automatically transfer certain values from the existing table record as default values for the new table record. This streamlines data entry for people using model-driven apps. Application users see the mapped values and can edit them before saving the entity.

For developers creating custom clients, the same behavior can be achieved by using the InitializeFrom message (Organization service InitializeFromRequest Class or Web API InitializeFrom Function) to get the entity data with the configured default values set.

More information

See also

Dataverse tables