Navigation Properties

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. 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:

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. 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

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:

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:

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.

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:

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:

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:

systemRequirements.systemRequirement — from UserNeed through the association to SystemRequirement
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.

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

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 defines the structural context in which navigation properties exist
Link Cardinality determines whether a navigation property is scalar or a collection, affecting both UI rendering and expansion patterns
Source Configuration uses navigation properties in expand blocks to load related data
Hierarchy and Traceability is the architectural goal that navigation properties enable — building multi-level views across entity types
Data Model vs Sheet Configuration 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. For column binding syntax and expansion path setup, see the Sheet Configuration Guides.

What Navigation Properties Are

How Navigation Properties Are Defined

Directionality: Direct vs Back

How Cardinality Shapes Navigation Properties

Many-to-One (N:1)

One-to-Many (1:N)

Many-to-Many (M:N)

The Three Layers: Model, Source, Columns

Dot-Notation Binding Paths

Scalar vs Collection Navigation Properties

Built-In Navigation Properties

Common Misconceptions

Relationship to Other Concepts

​What Navigation Properties Are

​How Navigation Properties Are Defined

​Directionality: Direct vs Back

​How Cardinality Shapes Navigation Properties

​Many-to-One (N:1)

​One-to-Many (1:N)

​Many-to-Many (M:N)

​The Three Layers: Model, Source, Columns

​Dot-Notation Binding Paths

​Scalar vs Collection Navigation Properties

​Built-In Navigation Properties

​Common Misconceptions

​Relationship to Other Concepts

What Navigation Properties Are

How Navigation Properties Are Defined

Directionality: Direct vs Back

How Cardinality Shapes Navigation Properties

Many-to-One (N:1)

One-to-Many (1:N)

Many-to-Many (M:N)

The Three Layers: Model, Source, Columns

Dot-Notation Binding Paths

Scalar vs Collection Navigation Properties

Built-In Navigation Properties

Common Misconceptions

Relationship to Other Concepts