Dynamics Community Forum Thread Details

Are OData navigation property names stable accross organizations?

Hi,

Background:

we use OData for client side extensions within our managed solution.

For some OData requests navigation property names are required.

Example:

data/v8.0/pt_examples$expand=owninguser(...)

So what we did is to determine the needed navigation propery names at development time and hardcoded our OData requests.

After years one of our customers reported an error.

Turns out that some navigation property names in the customer's organization have changed after importing the last version of our managed solution.

In the customer's org the navigation property is named owninguser_system now, so the request should look like:

data/v8.0/pt_examples$expand=owninguser_systemuser(...)

In order to fix that, we would need to determine the navigation property names at runtime, e.g. with:

data/v8.0/EntityDefinitions(LogicalName='pt_example')/ManyToOneRelationships?$select=SchemaName,ReferencingEntityNavigationPropertyName,ReferencingAttribute

This works, but it considerably complicates the client side code and also has a hit on performance (even if we cache the metadata).

Questions:

Is this really the way to go?
Are navigation property names really not stable accross organizations?
Or is there something special at our customer's organization?
How do you craft your OData requests with regard to navigation property names?

Additional information:

The custom entities in our managed solution cannot be customized. So there are no unknown, conflicting lookup fields, which could cause a naming clash.
Our customer migrated from on premise to online some years ago, and there was a another problem related to entity metadata, which was fixed by Microsoft support. Maybe it is a problem with the entity metadata in the customer's organization after all.

Thanks!

Johannes.

Categories:

Dynamics 365 Sales

Hi Johannes R,

1) Issue
In Dynamics 365 Sales, OData client-side requests depend on navigation property names that unexpectedly differ across environments, causing requests such as $expand to fail after solution deployment.

Observed behavior:
- Navigation properties like owninguser work in one environment but not in another
- In the customer environment, the same relationship appears as owninguser_systemuser
- Managed solution deployment results in metadata differences
- Hardcoded OData queries break when navigation property names change

2) Reason
Navigation property names in Dataverse are not guaranteed to be stable across environments due to how relationships and metadata are generated and resolved.

Potential contributing factors include:
A) Relationship schema name conflicts
- When multiple relationships target the same entity (for example multiple lookups to systemuser), Dataverse ensures uniqueness
- It appends suffixes such as _systemuser or numeric values
- This results in different navigation property names across environments

B) Solution import and layering behavior
- Managed solutions interact with existing metadata in the target environment
- If a relationship with a similar name already exists, Dataverse renames the navigation property to avoid conflicts
- This can occur even if the entity is locked from customization

C) Differences between environments
- Environments may have:
- Legacy customizations
- Removed or recreated relationships
- Historical solutions
- These differences influence metadata generation during import

D) On-premise to online migration artifacts
- Migration can leave inconsistent metadata states
- Relationship definitions may be rehydrated differently in Dataverse online
- This can lead to unexpected navigation property naming

E) OData abstraction limitations
- OData relies on logical metadata layer
- Navigation properties reflect relationship metadata, not fixed API contracts
- Therefore they are inherently environment-dependent

F) Hardcoding navigation property names
- Hardcoding assumes consistent metadata
- This is not reliable in Dataverse, especially across customers or tenants

3) Resolution
Step 1: Avoid hardcoding navigation property names
- Do not rely on static navigation property names in client-side code
- Treat them as environment-dependent metadata

Step 2: Retrieve metadata dynamically
- Use the EntityDefinitions endpoint to fetch relationship metadata at runtime
- Example:
/EntityDefinitions(LogicalName='pt_example')/ManyToOneRelationships?$select=SchemaName,ReferencingEntityNavigationPropertyName,ReferencingAttribute
- Extract the correct navigation property name dynamically

Step 3: Implement metadata caching
- Cache retrieved metadata in memory or browser storage
- Refresh periodically or on version changes
- Reduces performance impact of repeated metadata calls

Step 4: Use schema names to identify relationships
- Match relationships using:
- SchemaName
- ReferencingAttribute
- Do not rely on navigation property string directly

Step 5: Introduce abstraction layer in code
- Build a helper service that resolves navigation property names
- Centralize all OData query construction
- Prevent duplication and reduce maintenance effort

Step 6: Validate metadata consistency during deployment
- After solution import, validate:
- Relationship schema names
- Navigation property mappings
- Include automated validation in release pipeline if possible

Step 7: Minimize duplicate or conflicting relationships
- Review solution design to avoid multiple lookups to same entity where unnecessary
- This reduces chances of suffix-based renaming

Step 8: Consider using Dataverse Web API expand alternatives
- In some cases, retrieve related data via:
- Separate queries
- Bound functions
- This avoids reliance on navigation property naming

Step 9: Document environment-specific behavior
- Maintain documentation stating that navigation property names are not stable
- Ensure development teams follow dynamic resolution pattern

For a more detailed answer, please provide more information.

Rg,

Alexander

*Due to the complex and different possibilities of deploying Dynamics 365 I highly recommend not to setup the application without some expert/partner or support. (For more information contact me under anassl@inno-solutions.info or visit www.inno-solutions.de)

*The Information comes directly from the manufacturer or provider and are validated (not guaranteed) up to date of creation of the posting.

References: