Every relationship in the domain model connects a from entity type to a to entity type. The direct direction creates a navigation property on the from entity that points toward the to entity. The back direction creates a navigation property on the to entity that points back toward the from entity.The diagram above shows a relationship from UserNeed to SystemRequirement. The forward (direct) navigation property systemRequirements is placed on UserNeed, while the reverse (back) navigation property userNeeds is placed on SystemRequirement.
The direct property defines the navigation property created on the source (from) entity type. It controls how the from entity navigates toward the to entity.
Name
Type
Default
Description
direct
object
None
Forward navigation property definition created on the source entity type. Required for defining the forward traversal path.
direct.name
string
Required
Navigation property name for traversing from source to target entities. Used in expansion paths, column bindings, and queries. Must be unique within the source entity type.
direct.constraints
object
None
Optional constraint configuration for filtering accessible entities through this direction. Supports load, pick, and create constraint scopes.
The back property defines the navigation property created on the target (to) entity type. It enables reverse traversal from the to entity back to the from entity.
Name
Type
Default
Description
back
object
None
Reverse navigation property definition created on the target entity type. Required for defining the reverse traversal path.
back.name
string
Required
Navigation property name for traversing from target back to source entities. Used in expansion paths, column bindings, and queries. Must be unique within the target entity type.
back.constraints
object
None
Optional constraint configuration for filtering accessible entities in the reverse direction. Supports load, pick, and create constraint scopes.
Every relationship requires both a direct and a back definition. Even if you only intend to traverse in one direction, you must provide names for both sides so the domain model can fully resolve the bidirectional link.
Navigation property names follow consistent conventions that signal the cardinality and direction of the relationship:
Cardinality
direct.name (on from)
back.name (on to)
Naming Pattern
many-to-one
Singular (e.g., chapter)
Plural (e.g., userNeeds)
Direct side is scalar, back side is a collection
one-to-many
Plural (e.g., systemRequirements)
Singular (e.g., userNeed)
Direct side is a collection, back side is scalar
many-to-many
Plural (e.g., systemRequirements)
Plural (e.g., userNeeds)
Both sides are collections (association entity used internally)
Navigation property names use camelCase: systemRequirements, userNeeds, designRequirements. Match the entity type name but adjust case and pluralization to reflect the cardinality.
Here direct.name: chapter is singular because each UserNeed belongs to exactly one Chapter. The back.name: userNeeds is plural because each Chapter may contain multiple user needs.
The direct/back syntax supports attaching constraints to individual navigation directions. Constraints filter which entities are visible when expanding, picking, or creating through a particular direction.Each direction object supports three constraint scopes:
Scope
Purpose
load
Filters entities loaded during sheet expansion. Controls which related items appear as child rows.
pick
Filters the picker dialog when a user selects a related entity from a list.
create
Filters the context when creating a new entity through this navigation direction.
In this example, the userNeeds back-navigation property is filtered to only include items from documents that share the same component as the source entity’s document. The $context.source.document.component expression dynamically resolves the component value at runtime. See Context Expressions Reference for the full expression syntax.
Here the pick constraint on the designRequirements direct-navigation property restricts the picker dialog to only show design requirements from documents in the Design module folder.
The cardinality of the relationship determines how the navigation property behaves at runtime. The direction (direct vs back) combined with the cardinality determines whether a property resolves to a single entity or a collection.
Cardinality
direct Resolves To
back Resolves To
many-to-one
Single entity (scalar)
Collection of entities
one-to-many
Collection of entities
Single entity (scalar)
many-to-many
Collection of entities (via association)
Collection of entities (via association)
For many-to-many relationships, the expansion path requires two levels: first the association collection, then the target entity within it. For example, systemRequirements (association) followed by systemRequirement (target). See the column binding examples below.
Navigation property names become the segments of dot-separated binding paths in sheet configuration columns. The binding path pattern depends on the cardinality:
For many-to-one relationships using the direct direction, the navigation property resolves to a single entity. Column bindings access properties directly:
columns: chapter: title: Chapter display: title list: search: - title chapter.title: title: Chapter Title isReadOnly: true
chapter provides a single-value reference picker (scalar navigation property).
chapter.title accesses the title field of the referenced Chapter entity.
The userNeeds column triggers expansion into a new sheet level showing all child user needs. No dot-notation is needed since the expand directly opens the child level.
For many-to-many relationships, column binding uses a two-part path through the association entity:
columns: title: title: Title hasFocus: true systemRequirements.systemRequirement: title: System Requirement list: search: - objectId - title createNew: true systemRequirements.systemRequirement.title: title: SysReq Title hasFocus: true
The pattern is <associationNavProp>.<targetEntityNavProp>. The first segment (systemRequirements) navigates to the association collection; the second segment (systemRequirement) resolves to the target entity. This acts as a multi-item reference picker.
Navigation property names are referenced in the sources configuration to define which related entities are loaded when the sheet expands. The expand list uses direct.name or back.name values to traverse the entity graph:
Each name in the expand tree must match a navigation property defined by a direct or back direction on the queried entity type. The nesting depth determines how many levels of related entities are loaded. See Sources and Expand Clause for full details.
