What Navigation Properties Are
A navigation property is a named reference on an entity type that points to one or more related entities of a different type. When you define a relationship between two entity types in your domain model, Powersheet automatically generates navigation properties on both sides of the relationship. These properties become the building blocks for column binding paths in your sheet configuration and for expansion paths in your data sources.
For example, when you define a relationship from UserNeed to SystemRequirement, two navigation properties are created:
- A forward (direct) property on
UserNeed pointing to its related SystemRequirement entities
- A backward (back) property on
SystemRequirement pointing back to the originating UserNeed
Navigation properties do not store data themselves. They are computed references that Powersheet resolves at runtime by querying Polarion link roles. The domain model simply gives these traversal paths a name so that sheet configurations and source expansion paths can reference them consistently.
How Navigation Properties Are Defined
Navigation properties are defined exclusively in the relationships section of the domain model YAML. Each relationship entry creates a pair of navigation properties using direct and back notation:
relationships:
- from: UserNeed
to: SystemRequirement
cardinality: many-to-many
storage: linkedWorkItems
linkRole: refines
direct:
name: systemRequirements
back:
name: userNeed
direct block defines the forward navigation property — created on the from entity type (UserNeed in this example). The back block defines the reverse navigation property — created on the to entity type (SystemRequirement). The property names you choose here become the segments used in binding paths and expansion paths throughout your sheet configuration.
Navigation property names follow camelCase convention. Use a plural form for the “many” side of a relationship (e.g., systemRequirements) and a singular form for the “one” side (e.g., chapter). This naming convention signals the expected cardinality and makes configurations more readable.
Directionality: Direct vs Back
Every relationship in a domain model is inherently directional. Understanding which direction you are traversing is essential for building correct expansion paths and column bindings.
Direct (forward): Follows the relationship from the from entity to the to entity. If a UserNeed relates to a SystemRequirement, the direct navigation property on UserNeed points toward SystemRequirement.
Back (reverse): Follows the relationship in the opposite direction. The back navigation property on SystemRequirement points back toward UserNeed.
An analogy helps here: imagine a one-way street sign between two neighborhoods. The direct property lets you travel in the direction the sign points. The back property lets you travel in the opposite direction. Both directions are always available — the domain model creates doorways in both directions for every relationship.
| Direction | Defined on | Points to | Typical naming |
|---|
direct | from entity type | to entity type | Plural if collection, singular if scalar |
back | to entity type | from entity type | Plural if collection, singular if scalar |
How Cardinality Shapes Navigation Properties
The cardinality of a relationship determines whether a navigation property resolves to a single entity (scalar) or a collection of entities. This distinction has direct consequences for how the sheet renders data and how you write column bindings.
Many-to-One (N:1)
In a many-to-one relationship, the direct navigation property is scalar — it points to exactly one entity. For example, each UserNeed belongs to exactly one Chapter:
relationships:
- from: UserNeed
to: Chapter
cardinality: many-to-one
storage: linkedWorkItems
linkRole: parent
direct:
name: chapter
back:
name: userNeeds
chapter is a scalar property on UserNeed (each user need has one chapter), while userNeeds is a collection property on Chapter (each chapter has many user needs). In the sheet, a scalar navigation property renders as a single-value reference picker, while its reverse collection side expands into child rows.
Source and column usage:
sources:
- id: user_needs
query:
from: UserNeed
expand:
- name: chapter
columns:
title:
title: Title
hasFocus: true
chapter:
title: Chapter
display: title
list:
search:
- title
chapter.title:
title: Chapter Title
isReadOnly: true
chapter provides a single-value reference picker. The column chapter.title is a read-only display of the referenced Chapter’s title field.
One-to-Many (1:N)
One-to-many is the reverse perspective of many-to-one. If you query from Chapter and expand userNeeds, each chapter row gains child rows for its user needs. The back property userNeeds acts as the collection side:
sources:
- id: chapters
query:
from: Chapter
expand:
- name: userNeeds
columns:
title:
title: Chapter
hasFocus: true
userNeeds:
title: User Need
hasFocus: true
userNeeds navigation property to load all related UserNeed entities as child rows under each chapter. No dot-notation is needed — the expand directly opens the child level.
Many-to-Many (M:N)
Many-to-many relationships introduce an important concept: the association entity. Because both sides of the relationship are collections, Powersheet uses a two-level navigation path to traverse from one entity type to another through the association.
relationships:
- from: SystemRequirement
to: UserNeed
cardinality: many-to-many
storage: linkedWorkItems
linkRole: decomposes
direct:
name: userNeeds
back:
name: systemRequirements
sources:
- id: user_needs
query:
from: UserNeed
expand:
- name: systemRequirements
expand:
- name: systemRequirement
systemRequirements) reaches the association entity. The second level (systemRequirement) reaches the actual target entity. This two-level pattern is reflected in column binding paths as well: systemRequirements.systemRequirement.
Many-to-many relationships always require a two-level expansion in your sources configuration. If you only expand one level, you will reach the association entity but not the actual target entity, resulting in empty or incorrect column data.
The Three Layers: Model, Source, Columns
Navigation properties form the connective tissue between three configuration layers. Understanding how these layers reference each other is fundamental to working with Powersheet.
Domain model defines the relationships and assigns navigation property names via direct.name and back.name. This layer answers: “What entities exist and how are they related?”
Sources use navigation property names in expand blocks to tell Powersheet which related entities to load. This layer answers: “What data should the sheet fetch?”
Columns use dot-notation binding paths built from navigation property names to display specific fields of related entities. This layer answers: “What should the user see?”
| Layer | Uses navigation properties for | Example |
|---|
| Domain model | Defining named traversal paths | direct: { name: chapter } |
| Sources | Specifying which relationships to expand | expand: [{ name: chapter }] |
| Columns | Building binding paths to display data | chapter.title as column key |
direct.name: chapter but your column references chapters.title, the binding will fail silently and the column will appear empty.
A single typo in a navigation property name can cause an entire column or expansion level to silently produce no data. Always verify that the names in your relationships block, sources.expand, and columns keys match exactly.
Dot-Notation Binding Paths
Column keys in your sheet configuration use dot-notation to traverse navigation properties and access fields on related entities. Each dot-separated segment corresponds to one navigation property traversal.
Consider a three-level hierarchy: UserNeed relates to SystemRequirement, which relates to DesignRequirement:
columns:
title:
title: User Need
systemRequirements.systemRequirement:
title: System Requirement
systemRequirements.systemRequirement.designRequirements.designRequirement:
title: Design Requirement
systemRequirements.systemRequirement.designRequirements.designRequirement traverses two relationships:
systemRequirements.systemRequirement — from UserNeed through the association to SystemRequirementdesignRequirements.designRequirement — from SystemRequirement through the association to DesignRequirement
Each pair of segments represents one many-to-many hop. To access a specific field on the target entity, append the property name: systemRequirements.systemRequirement.severity displays the severity field of the related SystemRequirement.
The depth of your dot-notation path determines the row level in the sheet hierarchy. Root entity columns have no dots (level 0). First-level navigation adds one or two segments (level 1). Each additional relationship hop adds another level.
Deep navigation paths (three or more relationship hops) may impact query performance depending on the volume of linked work items. Test with representative data sets before deploying deeply nested configurations to production.
Scalar vs Collection Navigation Properties
The distinction between scalar and collection navigation properties determines how the sheet renders data and which UI controls are available:
Scalar properties (from the “one” side of a relationship) resolve to a single entity. In the sheet, these render as:
- A reference picker allowing the user to select one related entity
- Read-only display of a related entity’s field when accessed via dot-notation (e.g.,
chapter.title)
Collection properties (from the “many” side of a relationship) resolve to multiple entities. In the sheet, these render as:
- Child rows that expand underneath the parent row, creating a new hierarchy level
- Multi-item reference pickers when the column is configured with
multiItem: true
The cardinality table below summarizes the relationship between model definitions and sheet behavior:
| Cardinality | Direct property | Back property | Source expand | Column binding | UI behavior |
|---|
| N:1 | Scalar (chapter) | Collection (userNeeds) | - name: chapter | chapter, chapter.title | Single-value ref picker |
| 1:N | Collection (userNeeds) | Scalar (chapter) | - name: userNeeds | userNeeds (child rows) | New grid level |
| M:N | Collection | Collection | Two-level: systemRequirements then systemRequirement | systemRequirements.systemRequirement | Multi-item ref picker |
Built-In Navigation Properties
Every entity type in Powersheet automatically receives two built-in navigation properties, regardless of what you define in the relationships section:
| Property | Target | Description |
|---|
document | Document | Links the entity to its containing Polarion LiveDoc |
project | Project | Links the entity to its Polarion project |
document.title) and in picker constraints to scope entity selection by document or project.
Common Misconceptions
“I can define navigation properties directly on entity types.” Navigation properties are created exclusively through the relationships block. You cannot declare them inline within an entity type definition. The properties section of an entity type is for data fields (like description, severity) — not for navigation.
“Navigation properties store links.” Navigation properties do not store anything. The actual link data is persisted through Polarion’s native link mechanism (specified by storage: linkedWorkItems and linkRole). Navigation properties are runtime-resolved references that query these links.
“Navigation properties are the same as Polarion link roles.” A link role is the storage mechanism in Polarion; a navigation property is the named accessor that Powersheet creates on top of that link role. Multiple relationships can use the same link role but create different navigation properties with different names.
“Singular names mean one-to-one relationships.” The naming convention (singular vs plural) is a readability guideline, not a technical constraint. Powersheet determines cardinality from the cardinality field, not from the property name. However, following the convention consistently prevents confusion when reading configurations.
“I only need to expand one level for many-to-many.” Many-to-many relationships always require two expansion levels in sources — one for the association and one for the target entity. A single-level expansion will only reach the association, leaving target entity columns empty.
Relationship to Other Concepts
Navigation properties connect to several other areas of the Powersheet configuration system:
For practical guidance on configuring domain models with navigation properties, see the Data Model Guides. For column binding syntax and expansion path setup, see the Sheet Configuration Guides.
