Navigation Directions

See also: Relationships | Properties | Binding Syntax

Direction Overview

Every relationship in the data 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.

Direction Properties

Direct (Forward) Direction

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.

Back (Reverse) Direction

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 data model can fully resolve the bidirectional link.

Naming Conventions

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.

Relationship Declaration Syntax

The direct and back objects are nested inside each relationship entry in the relationships array of the data model YAML.

Basic Declaration

relationships:
  - from: UserNeed
    to: SystemRequirement
    cardinality: many-to-many
    storage: linkedWorkItems
    linkRole: decomposes
    direct:
      name: systemRequirements
    back:
      name: userNeeds

In this declaration:

direct.name: systemRequirements is added to the UserNeed entity type, allowing traversal from user needs to their linked system requirements.
back.name: userNeeds is added to the SystemRequirement entity type, allowing reverse traversal from system requirements back to user needs.

Many-to-One Declaration

relationships:
  - from: UserNeed
    to: Chapter
    cardinality: many-to-one
    storage: linkedWorkItems
    linkRole: parent
    direct:
      name: chapter
    back:
      name: userNeeds

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.

Constraint on Back Direction

relationships:
  - from: UserNeed
    to: SystemRequirement
    cardinality: one-to-many
    storage: linkedWorkItems
    linkRole: refines
    direct:
      name: systemRequirements
    back:
      name: userNeeds
      constraints:
        load:
          document:
            component: $context.source.document.component

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.

Constraint on Direct Direction

relationships:
  - from: SystemRequirement
    to: DesignRequirement
    cardinality: one-to-many
    storage: linkedWorkItems
    linkRole: refines
    direct:
      name: designRequirements
      constraints:
        pick:
          document:
            moduleFolder: Design
    back:
      name: systemRequirements

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.

How Directions Map to Cardinality

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.

The data model does not support one-to-one cardinality. Relationships must be declared as many-to-one, one-to-many, or many-to-many. To model a one-to-one association, use many-to-one and enforce uniqueness through constraints or workflow rules.

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.

For one-to-many relationships, the navigation property expands into child rows:

columns:
  title:
    title: Chapter
    hasFocus: true
  userNeeds:
    title: Title
    hasFocus: true

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.

Expansion Paths and Sources

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:

sources:
  - id: requirements
    query:
      from: UserNeed
    expand:
      - name: systemRequirements
        expand:
          - name: designRequirements

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.

Complete YAML Example

The following data model demonstrates navigation directions across a multi-level RTM hierarchy with constraints:

domainModelTypes:
  Chapter:
    polarionType: heading

  UserNeed:
    polarionType: user_need
    properties:
      description:
      severity:

  SystemRequirement:
    polarionType: sys_req
    properties:
      description:
      severity:

  DesignRequirement:
    polarionType: des_req
    properties:
      description:

relationships:
  - from: UserNeed
    to: Chapter
    cardinality: many-to-one
    storage: linkedWorkItems
    linkRole: parent
    direct:
      name: chapter
    back:
      name: userNeeds

  - from: SystemRequirement
    to: UserNeed
    cardinality: many-to-many
    storage: linkedWorkItems
    linkRole: decomposes
    direct:
      name: userNeeds
    back:
      name: systemRequirements

  - from: DesignRequirement
    to: SystemRequirement
    cardinality: one-to-many
    storage: linkedWorkItems
    linkRole: refines
    direct:
      name: systemRequirements
      constraints:
        pick:
          document:
            moduleFolder: Requirements
    back:
      name: designRequirements

This model creates the following navigation paths:

Entity Type	Navigation Property	Direction	Leads To	Cardinality
`UserNeed`	`chapter`	direct	`Chapter`	N:1 (scalar)
`Chapter`	`userNeeds`	back	`UserNeed`	1:N (collection)
`SystemRequirement`	`userNeeds`	direct	`UserNeed`	M:N (association)
`UserNeed`	`systemRequirements`	back	`SystemRequirement`	M:N (association)
`DesignRequirement`	`systemRequirements`	direct	`SystemRequirement`	1:N (collection)
`SystemRequirement`	`designRequirements`	back	`DesignRequirement`	1:N (collection)

Quick Reference: Direction Summary

Aspect	`direct`	`back`
Placed on	`from` entity type	`to` entity type
Traversal	Source to target	Target back to source
Required property	`direct.name`	`back.name`
Optional property	`direct.constraints`	`back.constraints`
Used in	`sources.expand.name`, column binding paths	`sources.expand.name`, column binding paths

Direction Overview

Direction Properties

Direct (Forward) Direction

Back (Reverse) Direction

Naming Conventions

Relationship Declaration Syntax

Basic Declaration

Many-to-One Declaration

Navigation with Constraints

Constraint on Back Direction

Constraint on Direct Direction

How Directions Map to Cardinality

Using Navigation Properties in Column Bindings

Scalar Navigation (N:1)

Collection Navigation (1:N)

Association Navigation (M:N)

Expansion Paths and Sources

Complete YAML Example

Quick Reference: Direction Summary

​Direction Overview

​Direction Properties

​Direct (Forward) Direction

​Back (Reverse) Direction

​Naming Conventions

​Relationship Declaration Syntax

​Basic Declaration

​Many-to-One Declaration

​Navigation with Constraints

​Constraint on Back Direction

​Constraint on Direct Direction

​How Directions Map to Cardinality

​Using Navigation Properties in Column Bindings

​Scalar Navigation (N:1)

​Collection Navigation (1:N)

​Association Navigation (M:N)

​Expansion Paths and Sources

​Complete YAML Example

​Quick Reference: Direction Summary

Direction Overview

Direction Properties

Direct (Forward) Direction

Back (Reverse) Direction

Naming Conventions

Relationship Declaration Syntax

Basic Declaration

Many-to-One Declaration

Navigation with Constraints

Constraint on Back Direction

Constraint on Direct Direction

How Directions Map to Cardinality

Using Navigation Properties in Column Bindings

Scalar Navigation (N:1)

Collection Navigation (1:N)

Association Navigation (M:N)

Expansion Paths and Sources

Complete YAML Example

Quick Reference: Direction Summary