Web API navigation properties
In the CSDL $metadata document, each entity type that isn't abstract has
NavigationProperty elements describe data that's related to the current entity type. When you retrieve a record, you can expand navigation properties to include related data.
The following table describes the attributes of
||The name of the navigation property; case-sensitive|
||The related entity type; can be to a single value or a collection of a type|
||The name of the navigation property on the other side of the relationship|
||Whether the value can be null|
Single-valued navigation properties
When a navigation property
Type refers to a single value, it represents a one-to-many relationship that creates a reference to another table record. This relationship is commonly called a lookup. The following example is the
createdby navigation property:
<NavigationProperty Name="createdby" Type="mscrm.systemuser" Nullable="false" Partner="lk_accountbase_createdby"> <ReferentialConstraint Property="_createdby_value" ReferencedProperty="systemuserid" /> </NavigationProperty>
This single-valued navigation property connects multiple
account records to a single
systemuser record. Each
systemuser record has a collection-valued navigation property named
lk_accountbase_createdby that connects it to the
account records the user has created.
These values are stored in relationship definitions. You can access them using the SDK OneToManyRelationshipMetadata or the Web API OneToManyRelationshipMetadata entity type, as described in the following table.
||The name of the single-valued navigation property.|
||The name of the collection-valued navigation property.|
Single-valued navigation properties have a
ReferentialConstraint with a
Property attribute that refers to a lookup property. Lookup properties use the following naming convention:
_<name>_value. Learn more about lookup properties.
ReferentialConstraint has a
ReferencedProperty attribute that identifies the primary key name of the related entity type.
In most cases, the
<name> found in the lookup property matches the name of the navigation property, except when the single-valued navigation property represents a multi-table lookup.
When the single-valued navigation property is part of a multi-table, or polymorphic, lookup, a single lookup property is the
ReferentialConstraint for more than one single-valued navigation property.
An entity type may have something like the following combination, where a single
_customerid_value lookup property supports multiple single-valued navigation properties that represent a multi-table lookup. There is one single-valued navigation property for each type of table supported by the multi-table lookup.
<EntityType Name="socialprofile" BaseType="mscrm.crmbaseentity"> <Key> <PropertyRef Name="socialprofileid" /> </Key> <Property Name="_customerid_value" <!-- lookup property --> Type="Edm.Guid"> <Annotation Term="Org.OData.Core.V1.Description" String="Shows the customer that this social profile belongs to." /> </Property> <NavigationProperty Name="customerid_contact" <!-- Name different from lookup property --> Type="mscrm.contact" Nullable="false" Partner="Socialprofile_customer_contacts"> <ReferentialConstraint Property="_customerid_value" <!-- Reference to lookup property --> ReferencedProperty="contactid" /> </NavigationProperty> <NavigationProperty Name="customerid_account" <!-- Name different from lookup property --> Type="mscrm.account" Nullable="false" Partner="Socialprofile_customer_accounts"> <ReferentialConstraint Property="_customerid_value" <!-- Reference to lookup property --> ReferencedProperty="accountid" /> </NavigationProperty> </EntityType>
In these cases, setting the value of any of the single-valued navigation properties sets all the other participating single-valued navigation properties to null. The corresponding lookup property GUID value changes, but you need to retrieve specific annotations to know which table it now refers to. More information: Lookup property data
Collection-valued navigation properties
When a navigation property
Type refers to a collection value, it represents a many-to-one or many-to-many relationship. The following example is the account entity
Account_Tasks navigation property:
<NavigationProperty Name="Account_Tasks" Type="Collection(mscrm.task)" Partner="regardingobjectid_account_task" />
This navigation property connects an
account record to many
task records. Each
task has a single-valued navigation property named
regardingobjectid_account_task that refers to the
account as the regarding object.
The way you work with collection-valued navigation properties using OData is the same regardless of whether the relationship is one-to-many or many-to-many. Both are considered collections and you interact with them the same way.
A many-to-one relationship is the mirror image of the one-to-many relationship. It has a partner single-valued navigation property. In the earlier single-valued navigation properties example, we looked at the
createdby single-valued navigation property for the
account entity type.
systemuser entity type, the collection-valued navigation property partner named
<NavigationProperty Name="lk_accountbase_createdby" Type="Collection(mscrm.account)" Partner="createdby" />
Name and the
Partner of the collection-valued navigation property are the same, it represents a many-to-many relationship.
Many-to-many relationships have some implementation details you can find in the service documents. For most use cases, you can ignore them.
For example, every many-to-many relationship has an intersect table that supports it. These intersect tables have entity types that typically have four read-only properties. In the following example, the
teammembership entity type is an intersect table that supports a many-to-many relationship between the
team entity types:
<EntityType Name="teammembership" BaseType="mscrm.crmbaseentity"> <Key> <PropertyRef Name="teammembershipid" /> </Key> <Property Name="systemuserid" Type="Edm.Guid" /> <Property Name="versionnumber" Type="Edm.Int64" /> <Property Name="teammembershipid" Type="Edm.Guid" /> <Property Name="teamid" Type="Edm.Guid" /> </EntityType>
You can't work with entity types that represent intersect tables directly because all the properties are read-only. Perform operations on the respective collection-valued navigation properties for each entity type. More information: Associate and disassociate table rows using the Web API
For this many-to-many relationship, the
systemuser entity type has the following collection-valued navigation property:
<NavigationProperty Name="teammembership_association" Type="Collection(mscrm.team)" Partner="teammembership_association" />
team entity type has this collection-valued navigation property:
<NavigationProperty Name="teammembership_association" Type="Collection(mscrm.systemuser)" Partner="teammembership_association" />
These values are stored in relationship definitions. You can access them using the SDK ManyToManyRelationshipMetadata or the Web API ManyToManyRelationshipMetadata entity type, as described in the following table.
||The name of the collection-valued navigation property for one of the entity types|
||The name of the collection-valued navigation property for the other entity type|
Learn about Action definitions.
Web API types and operations
Web API service documents
Web API EntityTypes
Web API properties
Web API actions
Web API functions
Web API complex and enumeration types
Use the Dataverse Web API
OData Version 4.0. Part 3: Common Schema Definition Language (CSDL) Plus Errata 03 7.1 Element edm:NavigationProperty