Skip to main content

​
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 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
The names of these navigation properties are specified via fromNavPropName (or direct.name) and toNavPropName (or back.name) in the relationship definition. diagram

​
How Navigation Properties Are Named

Navigation property names are defined in the relationships section of the domain model YAML. There are two naming conventions, depending on which relationship syntax you use:
Syntax StyleForward PropertyBackward Property
Flat stylefromNavPropNametoNavPropName
Nested styledirect.nameback.name
Both styles produce the same result. The property names you choose become the segments used in binding paths and expansion paths throughout your sheet configuration. 
relationships:
  - from: UserNeed
    to: SystemRequirement
    cardinality: one-to-many
    storage: linkedWorkItems
    linkRole: refines
    fromNavPropName: systemRequirements
    toNavPropName: userNeed
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., userNeed).

​
How Navigation Properties Enable Hierarchical Views

Navigation properties are the mechanism that makes hierarchical sheet rendering possible. When the sheet loads data, it uses expansion paths defined in the sources section to follow navigation properties and load related entities. Each expansion step traverses one navigation property, creating a new level in the row hierarchy. The sheet computes row levels from column binding paths. The root entity is always level 0 (the upstream level). Each navigation property traversal creates a downstream level, allowing the sheet to display parent-child relationships as nested rows. For example, a binding path of systemRequirements.systemRequirement.title creates a level 1 row for each SystemRequirement beneath its parent UserNeed.

​
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:
PropertyTargetDescription
documentDocumentLinks the entity to its containing Polarion document
projectProjectLinks the entity to its Polarion project
These built-in properties support filtering, expansion, and foreign key lookups without any explicit configuration in the domain model. The cardinality of a relationship directly affects how navigation properties behave:
CardinalityForward Property ReturnsBack Property Returns
one-to-oneSingle entitySingle entity
one-to-manyCollection of entitiesSingle entity
many-to-oneSingle entityCollection of entities
many-to-manyCollection of entitiesCollection of entities
When a navigation property returns a collection, the sheet renders multiple child rows beneath the parent row. Columns bound to collection-valued navigation properties typically use multiItem: true in the sheet configuration.
Navigation properties are not 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.
In the sheet configuration, binding paths (column keys) chain navigation property names together with dot separators to reach properties on related entities. Each segment of the path corresponds to a navigation property traversal. 
columns:
  # Direct property on root entity
  title:
    title: Title
    width: 200

  # One level of navigation
  systemRequirements.systemRequirement.title:
    title: System Req Title
    width: 180

  # Two levels of navigation
  systemRequirements.systemRequirement.designRequirements.designRequirement.title:
    title: Design Req Title
    width: 180
Each dot-separated pair (e.g., systemRequirements.systemRequirement) represents a navigation property name followed by the entity type alias for that level. This pattern enables the sheet to render deeply nested hierarchies across the entire traceability chain.
The exact behavior of navigation property resolution for deeply nested paths (beyond three levels) should be verified in your specific Powersheet configuration, as performance characteristics may vary with depth.
Source Code
  • MetadataTest.java
  • DatabridgeMetadata.java
  • Relationship.java
  • todosBig_model.yaml
  • prod-powersheet-src/com.nextedy.powersheet.client/ltc-repo/__tests__/test-viewModel.ts