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

# Relationships

> The `relationships` array in the Nextedy POWERSHEET data model defines bidirectional associations between entity types.

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 <p className="mt-10 text-sm text-gray-400 dark:text-zinc-500 not-prose">
      Last reviewed on {formatted}
    </p>;
};

<Frame>
  <img src="https://mintcdn.com/none-17b4493f/-WiVljKlDztH36bB/powersheet/diagrams/reference/data-model/relationships/diagram-1.svg?fit=max&auto=format&n=-WiVljKlDztH36bB&q=85&s=0e1376f57649dd5c8bf1aa6cbea33e59" alt="diagram" style={{ width: "720px", maxWidth: "100%" }} width="720" height="200" data-path="powersheet/diagrams/reference/data-model/relationships/diagram-1.svg" />
</Frame>

## Structure

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

```yaml theme={null}
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](/powersheet/reference/data-model/cardinality), a storage mechanism, a [link role](/powersheet/reference/data-model/link-roles), 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](/powersheet/reference/data-model/cardinality).                               |
| `storage`     | `string` | Required                      | Persistence mechanism. Only `linkedWorkItems` is supported. See [Storage](#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](/powersheet/reference/data-model/link-roles). |
| `direct`      | `object` | Required                      | Forward navigation property configuration (from source to target). See [Navigation Properties](#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](#navigation-properties).                                                   |
| `back.name`   | `string` | Required (if `back` provided) | Navigation property name for reverse traversal.                                                                                                                                |

<Warning title="from/to reference entity type names">
  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).
</Warning>

## Navigation Properties

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 |

```yaml theme={null}
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                             |

<Tip title="Use camelCase for navigation property names">
  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.
</Tip>

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

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

See [Cardinality](/powersheet/reference/data-model/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. |

<Info title="Only linkedWorkItems is supported">
  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`.
</Info>

### 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](/powersheet/reference/data-model/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. |

<Info title="Verify in application">
  Permission flag behavior may depend on your Polarion project permissions and Powersheet version. Test in your environment to confirm the exact behavior.
</Info>

## Navigation Properties in Binding Paths

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

```yaml theme={null}
relationships:
  - from: UserNeed
    to: Chapter
    cardinality: many-to-one
    storage: linkedWorkItems
    linkRole: parent
    direct:
      name: chapter
    back:
      name: userNeeds
```

**Source configuration:**

```yaml theme={null}
sources:
  - id: user_needs
    query:
      from: UserNeed
    expand:
      - name: chapter
```

**Column bindings:**

```yaml theme={null}
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:**

```yaml theme={null}
sources:
  - id: chapters
    query:
      from: Chapter
    expand:
      - name: userNeeds
```

**Column bindings:**

```yaml theme={null}
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:**

```yaml theme={null}
relationships:
  - from: SystemRequirement
    to: UserNeed
    cardinality: many-to-many
    storage: linkedWorkItems
    linkRole: decomposes
    direct:
      name: userNeeds
    back:
      name: systemRequirements
```

**Source configuration:**

```yaml theme={null}
sources:
  - id: user_needs
    query:
      from: UserNeed
    expand:
      - name: systemRequirements
        expand:
          - name: systemRequirement
```

**Column bindings:**

```yaml theme={null}
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:

```yaml theme={null}
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.

## Related Pages

* [Cardinality](/powersheet/reference/data-model/cardinality) -- detailed rules for each cardinality option
* [Link Roles](/powersheet/reference/data-model/link-roles) -- configuring Polarion link roles for relationships
* [Data Model Types](/powersheet/reference/data-model/domainmodeltypes) -- entity type definitions referenced by `from` and `to`
* [Navigation Directions](/powersheet/reference/data-model/navigation-directions) -- how direction properties work internally
* [Binding Syntax](/powersheet/reference/sheet-config/binding-syntax) -- using navigation properties in column bindings
* [Sources](/powersheet/reference/sheet-config/sources) -- configuring expand paths that use navigation properties
* [Constraints](/powersheet/reference/data-model/constraints) -- filtering constraints applied to entity types in relationships

<LastReviewed date="2026-06-08" />