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

# Configure a Relationship

> Define a relationship between two entity types in your Nextedy POWERSHEET data model to enable hierarchical navigation and traceability in Siemens Polarion ALM.

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>;
};

## Prerequisites

* Both entity types must already exist in your `domainModelTypes` section
* A Polarion link role must be configured in your project for the relationship
* Access to the data model YAML file in your project's SVN repository

<Steps>
  <Step title="Identify the Relationship">
    Determine the source and target entity types, the cardinality, and which Polarion link role to use.

    | Decision        | Question                                 | Example             |
    | --------------- | ---------------------------------------- | ------------------- |
    | Source (`from`) | Which entity initiates the relationship? | `UserNeed`          |
    | Target (`to`)   | Which entity is being referenced?        | `SystemRequirement` |
    | Cardinality     | How many targets per source?             | `many-to-many`      |
    | Link role       | Which Polarion link role stores this?    | `decomposes`        |

    <Frame>
      <img src="https://mintcdn.com/none-17b4493f/3Zik2OH750CE3kB4/powersheet/diagrams/guides/data-model/configure-relationship/diagram-1.svg?fit=max&auto=format&n=3Zik2OH750CE3kB4&q=85&s=52938af91ea1ed98885ee5a4598a871f" alt="diagram" style={{ width: "500px", maxWidth: "100%" }} width="500" height="130" data-path="powersheet/diagrams/guides/data-model/configure-relationship/diagram-1.svg" />
    </Frame>
  </Step>

  <Step title="Add the Relationship to Your Data Model">
    Add an entry to the `relationships` array in your data model YAML. Each relationship uses `direct` and `back` objects to define the forward and reverse navigation property names.

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

    ### Relationship Properties

    | Property      | Type   | Required | Description                                                                                                                                                        |
    | ------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
    | `from`        | string | Yes      | Source entity type name. Must match a `domainModelTypes` key exactly.                                                                                              |
    | `to`          | string | Yes      | Target entity type name. Must match a `domainModelTypes` key exactly.                                                                                              |
    | `cardinality` | string | Yes      | Multiplicity: `many-to-one`, `one-to-many`, or `many-to-many`. See the [Cardinality reference](/powersheet/reference/data-model/cardinality) for supported values. |
    | `storage`     | string | Yes      | Persistence mechanism. Use `linkedWorkItems` for Polarion link-based relationships.                                                                                |
    | `linkRole`    | string | Yes      | Polarion link role ID. Must exist in your project's link role configuration.                                                                                       |
    | `direct`      | object | Yes      | Forward navigation property. Contains a `name` field used to traverse from source to target.                                                                       |
    | `back`        | object | Yes      | Reverse navigation property. Contains a `name` field used to traverse from target back to source.                                                                  |

    <Warning title="`from` and `to` Must Reference Entity Type Names">
      The `from` and `to` values must be data model entity type names (e.g., `UserNeed`), **not** Polarion work item type IDs (e.g., `user_need`). Using the Polarion type ID instead of the entity type name causes connection errors that are difficult to diagnose.
    </Warning>
  </Step>

  <Step title="Choose Navigation Property Names">
    The `direct.name` and `back.name` values define how you traverse the relationship in sheet configurations, expansion paths, and column bindings. Follow these naming conventions:

    * **Forward** (`direct.name`): Use the plural camelCase form of the **target** entity -- e.g., `systemRequirements` when the target is `SystemRequirement`
    * **Reverse** (`back.name`): Use the plural camelCase form of the **source** entity -- e.g., `userNeeds` when the source is `UserNeed`

    For `many-to-one` relationships, the forward navigation property should be **singular** (scalar), since it references exactly one target:

    ```yaml theme={null}
    # many-to-one: each UserNeed belongs to one Chapter
    - from: UserNeed
      to: Chapter
      cardinality: many-to-one
      storage: linkedWorkItems
      linkRole: parent
      direct:
        name: chapter          # singular -- scalar reference
      back:
        name: userNeeds        # plural -- collection of children
    ```

    <Tip title="Naming Convention Drives UI Behavior">
      The cardinality and navigation property name together determine what the sheet renders. A singular `direct.name` like `chapter` produces a single-value reference picker. A plural `back.name` like `userNeeds` produces expandable child rows or a multi-item picker, depending on how you bind columns.
    </Tip>
  </Step>

  <Step title="Configure by Cardinality">
    The cardinality you choose affects how sources expand and how columns bind. Use the following patterns.

    ### Many-to-One (N:1)

    Each source entity references exactly one target. The `direct.name` is singular.

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

    # Sheet source -- expand the scalar reference
    sources:
      - id: user_needs
        query:
          from: UserNeed
        expand:
          - name: chapter

    # Sheet columns -- dot-notation for target properties
    columns:
      chapter:
        title: Chapter
        display: title
        list:
          search:
            - title
      chapter.title:
        title: Chapter Title
        isReadOnly: true
    ```

    ### One-to-Many (1:N)

    Each source entity has multiple children. This is the reverse side of a many-to-one relationship, using the `back.name` collection property.

    ```yaml theme={null}
    # Sheet source -- expand the collection
    sources:
      - id: chapters
        query:
          from: Chapter
        expand:
          - name: userNeeds

    # Sheet columns -- collection expands into child rows
    columns:
      title:
        title: Chapter
        hasFocus: true
      userNeeds:
        title: User Need
        hasFocus: true
    ```

    ### Many-to-Many (M:N)

    Both sides can reference multiple entities. The expand uses an **association entity** pattern with two levels of expansion.

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

    # Sheet source -- two-level expand through association
    sources:
      - id: user_needs
        query:
          from: UserNeed
        expand:
          - name: systemRequirements
            expand:
              - name: systemRequirement

    # Sheet columns -- dot-notation through association
    columns:
      systemRequirements.systemRequirement:
        title: System Requirement
        list:
          search:
            - objectId
            - title
          createNew: true
      systemRequirements.systemRequirement.title:
        title: SysReq Title
        hasFocus: true
    ```

    <Warning title="Second Linked Entity Requires `multiItem: true`">
      When a sheet has two entity types linked to the same parent (e.g., design outputs and design verifications both linked to system requirements), the second linked column must be declared with `multiItem: true` in the sheet configuration. Omitting this property causes the second column to silently fail during initial setup.
    </Warning>
  </Step>

  <Step title="Verify the Relationship">
    After saving the data model YAML:

    1. Open a Powersheet that uses this data model
    2. Expand the source entity to confirm child rows or linked items appear
    3. Check that column bindings resolve correctly -- the referenced entity properties should display their values

    If the sheet does not load or shows errors, verify:

    * The `from` and `to` values match entity type names in `domainModelTypes` exactly (case-sensitive)
    * The `linkRole` value exists in your Polarion project's link role configuration
    * The `sources.model` property in your sheet configuration matches your custom data model name

    You should now see the related entities navigable through expansion paths in your sheet, with columns displaying the linked entity properties.

    <Tip title="Model Name Must Match">
      The `sources.model` property in your sheet configuration must match the data model name -- not the default `rtm`. This is a common first-time setup mistake that causes model connection errors.
    </Tip>
  </Step>
</Steps>

## Quick Reference

| Cardinality | `direct.name`        | `back.name`                   | Source Expand                                            | Column Binding                         | UI Behavior                   |
| ----------- | -------------------- | ----------------------------- | -------------------------------------------------------- | -------------------------------------- | ----------------------------- |
| **N:1**     | `chapter` (singular) | `userNeeds` (plural)          | `- name: chapter`                                        | `chapter`, `chapter.title`             | Single-value reference picker |
| **1:N**     | reverse of N:1       | `userNeeds` (plural)          | `- name: userNeeds`                                      | `userNeeds`                            | Expandable child rows         |
| **M:N**     | `userNeeds` (plural) | `systemRequirements` (plural) | Two-level: `systemRequirements` then `systemRequirement` | `systemRequirements.systemRequirement` | Multi-item reference picker   |

## See Also

* [Create an Entity Type](/powersheet/guides/data-model/create-entity-type) -- define the entity types before adding relationships
* [Create Bidirectional Links](/powersheet/guides/data-model/create-bidirectional-links) -- advanced bidirectional linking patterns
* [Configure Many-to-Many Relationships](/powersheet/guides/data-model/configure-many-to-many) -- detailed M:N configuration
* [Data Model Reference](/powersheet/reference/data-model/index) -- complete property reference for data models
* [Cardinality Reference](/powersheet/reference/data-model/cardinality) -- supported cardinality values and their behavior
* [Configure Sources](/powersheet/guides/sheet-configuration/configure-sources) -- connect relationships to sheet expansion paths
* [Add a Column](/powersheet/guides/sheet-configuration/add-column) -- bind columns to relationship navigation properties

<LastReviewed date="2026-07-02" />