Relationships - Nextedy Documentation

Structure

Relationships are defined as a top-level array in the data model YAML, alongside domainModelTypes:

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

Each entry connects a source entity type (from) to a target entity type (to), specifies a cardinality, a storage mechanism, a link role, and two navigation properties that allow traversal in both directions.

Relationship Properties

Property	Type	Default	Description
`from`	`string`	Required	Source entity type name. Must match a key in `domainModelTypes`.
`to`	`string`	Required	Target entity type name. Must match a key in `domainModelTypes`.
`cardinality`	`string`	Required	Relationship multiplicity. One of `many-to-one`, `one-to-many`, `many-to-many`. See Cardinality.
`storage`	`string`	Required	Persistence mechanism. Only `linkedWorkItems` is supported. See Storage.
`linkRole`	`string`	Required	Polarion link role ID used to implement this relationship. Must exist in the project’s link role configuration. See Link Roles.
`direct`	`object`	Required	Forward navigation property configuration (from source to target). See Navigation Properties.
`direct.name`	`string`	Required	Navigation property name for forward traversal. Used in expansion paths and column bindings.
`back`	`object`	Optional	Reverse navigation property configuration (from target back to source). See Navigation Properties.
`back.name`	`string`	Required (if `back` provided)	Navigation property name for reverse traversal.

The from and to fields must reference names defined in domainModelTypes — not Polarion work item type IDs. For example, use UserNeed (the entity type name), not user_need (the Polarion type ID).

Every relationship creates navigation properties on the participating entity types. These properties enable:

Expansion paths in sheet source configurations
Column bindings using dot-notation in sheet column definitions
Query traversal across related entity types

Navigation properties are defined using the direct and back objects:

Direction	Object	Created On	Purpose
Forward	`direct`	Source (`from`) entity	Navigate from source to target
Reverse	`back`	Target (`to`) entity	Navigate from target back to source

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

In this example:

UserNeed gains the navigation property chapter (forward, to the Chapter entity)
Chapter gains the navigation property userNeeds (reverse, back to UserNeed entities)

Naming Conventions

Cardinality	Direct Name	Back Name	Rationale
`many-to-one`	Singular (`chapter`)	Plural (`userNeeds`)	Direct points to one target; back returns many sources
`one-to-many`	Plural (`userNeeds`)	Singular (`chapter`)	Direct points to many targets; back returns one source
`many-to-many`	Plural (`systemRequirements`)	Plural (`userNeeds`)	Both sides are collections

Navigation property names follow camelCase convention. Use singular names for scalar references and plural names for collection references. This naming directly maps to source expand entries and column binding paths.

Cardinality Options

The cardinality property determines how many entities can participate on each side of the relationship:

Value	From Side	To Side	Direct Property	Back Property
`many-to-one`	Single reference	Collection	Scalar	Collection
`one-to-many`	Collection	Single reference	Collection	Scalar
`many-to-many`	Collection	Collection	Collection (via association)	Collection (via association)

Cardinality affects three layers of configuration:

Data model — determines navigation property type (scalar vs. collection)
Sheet sources — determines expand pattern (single-level vs. two-level for M:N)
Sheet columns — determines binding syntax and UI behavior (picker vs. child rows)

See Cardinality for complete documentation on each option.

Storage

The storage property specifies how the relationship is persisted in Polarion.

Value	Description
`linkedWorkItems`	Uses Polarion’s native work item link mechanism. Requires `linkRole` to specify which link role implements the association.

The linkedWorkItems storage mechanism is the only supported option. It leverages Polarion’s built-in linked work items infrastructure, which stores relationships as typed links between work items using the configured linkRole.

Link Role Mapping

The linkRole value must correspond to a link role defined in the Polarion project configuration. Common link roles used in data models:

Link Role	Typical Usage
`parent`	Hierarchical parent-child relationships (e.g., `Chapter` to `UserNeed`)
`decomposes`	Decomposition relationships (e.g., `SystemRequirement` to `UserNeed`)
`refines`	Refinement relationships (e.g., `DesignRequirement` to `SystemRequirement`)
`mitigates`	Risk relationships (e.g., `RiskControl` to `Hazard`)
`verifies`	Verification relationships (e.g., test cases to requirements)

See Link Roles for detailed documentation on configuring and using Polarion link roles.

Permission Control

Relationships support permission flags that control CRUD operations through the sheet:

Property	Type	Default	Description
`createable`	`boolean`	See application	Whether new relationship instances can be created through the sheet.
`readable`	`boolean`	See application	Whether relationship instances are visible in queries and the sheet UI.

Permission flag behavior may depend on your Polarion project permissions and Powersheet version. Test in your environment to confirm the exact behavior.

Navigation property names created by relationships flow directly into sheet configuration. The three configuration layers — data model, sheet sources, and sheet columns — are connected through these navigation property names. The cardinality of the relationship determines the expand pattern and column binding syntax.

Many-to-One (N:1)

A scalar reference from source to a single target entity. Uses the direct navigation property. Data model:

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

Source configuration:

sources:
  - id: user_needs
    query:
      from: UserNeed
    expand:
      - name: chapter

Column bindings:

columns:
  title:
    title: Title
    hasFocus: true
  chapter:
    title: Chapter
    display: title
    list:
      search:
        - title
  chapter.title:
    title: Chapter Title
    isReadOnly: true

chapter — single-value reference picker (scalar navigation property, N:1)
chapter.title — read-only display of the referenced Chapter’s title via dot-notation

One-to-Many (1:N)

A collection of child entities accessible from a parent. Uses the back navigation property (reverse side of a many-to-one relationship). Source configuration:

sources:
  - id: chapters
    query:
      from: Chapter
    expand:
      - name: userNeeds

Column bindings:

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

userNeeds — expands into child rows, creating a new level in the sheet hierarchy
No dot-notation needed; the expand directly opens the child level

Many-to-Many (M:N)

Collections on both sides, navigated through an association entity. Uses a two-level expand. Data model:

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

Source configuration:

sources:
  - id: user_needs
    query:
      from: UserNeed
    expand:
      - name: systemRequirements
        expand:
          - name: systemRequirement

Column bindings:

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

M:N relationships use an association entity between the two types
Source expand is two levels: systemRequirements (association) then systemRequirement (target entity)
Column binding uses dot-notation: systemRequirements.systemRequirement
Acts as a multi-item reference picker in the sheet UI

Cardinality Summary

Cardinality	Model	Source Expand	Column Binding	UI Behavior
N:1	`cardinality: many-to-one`, `direct.name: chapter`	`- name: chapter`	`chapter`, `chapter.title`	Single-value reference picker
1:N	Reverse of N:1, `back.name: userNeeds`	`- name: userNeeds`	`userNeeds`	Child rows (new sheet level)
M:N	`cardinality: many-to-many`, `back.name: systemRequirements`	`- name: systemRequirements` then `- name: systemRequirement`	`systemRequirements.systemRequirement`	Multi-item reference picker

Complete YAML Example

A full data model demonstrating all relationship cardinalities across the standard RTM entity types:

domainModelTypes:
  Chapter:
    polarionType: heading

  UserNeed:
    polarionType: user_need
    properties:
      description:
      severity:

  SystemRequirement:
    polarionType: sys_req
    properties:
      description:
      severity:

  DesignRequirement:
    polarionType: des_req
    properties:
      description:

  Hazard:
    polarionType: hazard
    properties:
      description:

  RiskControl:
    polarionType: riskControl
    properties:
      description:

relationships:
  # N:1 -- each UserNeed belongs to one Chapter
  - from: UserNeed
    to: Chapter
    cardinality: many-to-one
    storage: linkedWorkItems
    linkRole: parent
    direct:
      name: chapter
    back:
      name: userNeeds

  # M:N -- UserNeeds decompose into SystemRequirements
  - from: SystemRequirement
    to: UserNeed
    cardinality: many-to-many
    storage: linkedWorkItems
    linkRole: decomposes
    direct:
      name: userNeeds
    back:
      name: systemRequirements

  # M:N -- SystemRequirements refine into DesignRequirements
  - from: DesignRequirement
    to: SystemRequirement
    cardinality: many-to-many
    storage: linkedWorkItems
    linkRole: refines
    direct:
      name: systemRequirements
    back:
      name: designRequirements

  # M:N -- Hazards linked to DesignRequirements
  - from: Hazard
    to: DesignRequirement
    cardinality: many-to-many
    storage: linkedWorkItems
    linkRole: refines
    direct:
      name: designRequirements
    back:
      name: hazards

  # M:N -- RiskControls mitigate Hazards
  - from: RiskControl
    to: Hazard
    cardinality: many-to-many
    storage: linkedWorkItems
    linkRole: mitigates
    direct:
      name: hazards
    back:
      name: riskControls

This model creates a full traceability chain: Chapter > UserNeed > SystemRequirement > DesignRequirement > Hazard > RiskControl. Each relationship uses linkedWorkItems storage with an appropriate Polarion link role, and defines both direct and back navigation properties for bidirectional traversal.

Cardinality — detailed rules for each cardinality option
Link Roles — configuring Polarion link roles for relationships
Data Model Types — entity type definitions referenced by from and to
Navigation Directions — how direction properties work internally
Binding Syntax — using navigation properties in column bindings
Sources — configuring expand paths that use navigation properties
Constraints — filtering constraints applied to entity types in relationships

​Structure

​Relationship Properties

​Navigation Properties

​Naming Conventions

​Cardinality Options

​Storage

​Link Role Mapping

​Permission Control

​Navigation Properties in Binding Paths

​Many-to-One (N:1)

​One-to-Many (1:N)

​Many-to-Many (M:N)

​Cardinality Summary

​Complete YAML Example

​Related Pages

Structure

Relationship Properties

Navigation Properties

Naming Conventions

Cardinality Options

Storage

Link Role Mapping

Permission Control

Navigation Properties in Binding Paths

Many-to-One (N:1)

One-to-Many (1:N)

Many-to-Many (M:N)

Cardinality Summary

Complete YAML Example

Related Pages