> ## Documentation Index
> Fetch the complete documentation index at: https://learn.nextedy.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Navigation Properties
> Nextedy POWERSHEET uses **navigation properties** to connect entity types within a data model, enabling the sheet to traverse relationships and display hierarchical data across multiple levels.
export const LastReviewed = ({date}) => {
if (!date) return null;
const formatted = new Date(`${date}T00:00:00Z`).toLocaleDateString("en-US", {
year: "numeric",
month: "long",
day: "numeric",
timeZone: "UTC"
});
return
Last reviewed on {formatted}
;
};
## 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 data 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 data 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 data model YAML. Each relationship entry creates a pair of navigation properties using `direct` and `back` notation:
```yaml theme={null}
relationships:
- from: UserNeed
to: SystemRequirement
cardinality: many-to-many
storage: linkedWorkItems
linkRole: refines
direct:
name: systemRequirements
back:
name: userNeed
```
The `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 data 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 data 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 |
The direction you choose in your source expansion determines which entity type serves as the root of your hierarchy and which entities appear as child rows.
## 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`:
```yaml theme={null}
relationships:
- from: UserNeed
to: Chapter
cardinality: many-to-one
storage: linkedWorkItems
linkRole: parent
direct:
name: chapter
back:
name: userNeeds
```
Here, `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:**
```yaml theme={null}
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
```
The column `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:
```yaml theme={null}
sources:
- id: chapters
query:
from: Chapter
expand:
- name: userNeeds
columns:
title:
title: Chapter
hasFocus: true
userNeeds:
title: User Need
hasFocus: true
```
The expand follows the `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.
```yaml theme={null}
relationships:
- from: SystemRequirement
to: UserNeed
cardinality: many-to-many
storage: linkedWorkItems
linkRole: decomposes
direct:
name: userNeeds
back:
name: systemRequirements
```
When expanding a many-to-many relationship in your sources, you specify two nested levels:
```yaml theme={null}
sources:
- id: user_needs
query:
from: UserNeed
expand:
- name: systemRequirements
expand:
- name: systemRequirement
```
The first level (`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.
**Data 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 |
| ---------- | ---------------------------------------- | ----------------------------- |
| Data 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 |
The names must match exactly across all three layers. If your model defines `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`:
```yaml theme={null}
columns:
title:
title: User Need
systemRequirements.systemRequirement:
title: System Requirement
systemRequirements.systemRequirement.designRequirements.designRequirement:
title: Design Requirement
```
The path `systemRequirements.systemRequirement.designRequirements.designRequirement` traverses two relationships:
1. `systemRequirements.systemRequirement` -- from `UserNeed` through the association to `SystemRequirement`
2. `designRequirements.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 |
These built-in properties support filtering, expansion, and foreign key lookups without any explicit configuration in the data model. You can use them in column bindings (e.g., `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:
* [Entity Types and Relationships](/powersheet/concepts/entity-types-and-relationships) defines the structural context in which navigation properties exist
* [Link Cardinality](/powersheet/concepts/link-cardinality) determines whether a navigation property is scalar or a collection, affecting both UI rendering and expansion patterns
* [Source Configuration](/powersheet/concepts/source-configuration) uses navigation properties in `expand` blocks to load related data
* [Hierarchy and Traceability](/powersheet/concepts/hierarchy-and-traceability) is the architectural goal that navigation properties enable -- building multi-level views across entity types
* [Data Model vs Sheet Configuration](/powersheet/concepts/data-model-vs-sheet-config) explains where navigation properties fit across the two configuration files
For practical guidance on configuring data models with navigation properties, see the [Data Model Guides](/powersheet/guides/data-model/index). For column binding syntax and expansion path setup, see the [Sheet Configuration Guides](/powersheet/guides/sheet-configuration/index).