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

# Navigation Directions

> Navigation directions in a Nextedy POWERSHEET data model define how relationships between entity types can be traversed.

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

See also: [Relationships](/powersheet/reference/data-model/relationships) | [Properties](/powersheet/reference/data-model/properties) | [Binding Syntax](/powersheet/reference/sheet-config/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.

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

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

<Note title="Both directions are always defined">
  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.
</Note>

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

<Tip title="Use camelCase consistently">
  Navigation property names use camelCase: `systemRequirements`, `userNeeds`, `designRequirements`. Match the entity type name but adjust case and pluralization to reflect the cardinality.
</Tip>

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

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

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

## Navigation with Constraints

The `direct`/`back` syntax supports attaching [constraints](/powersheet/reference/data-model/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

```yaml theme={null}
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](/powersheet/reference/data-model/context-expressions) for the full expression syntax.

### Constraint on Direct Direction

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

<Warning title="Many-to-many uses association entities">
  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.
</Warning>

<Note title="One-to-one is not supported">
  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.
</Note>

## Using Navigation Properties in Column Bindings

Navigation property names become the segments of dot-separated binding paths in sheet configuration columns. The binding path pattern depends on the cardinality:

### Scalar Navigation (N:1)

For `many-to-one` relationships using the `direct` direction, the navigation property resolves to a single entity. Column bindings access properties directly:

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

### Collection Navigation (1:N)

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

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

### Association Navigation (M:N)

For `many-to-many` relationships, column binding uses a two-part path through the association entity:

```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
```

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:

```yaml theme={null}
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](/powersheet/reference/sheet-config/sources) and [Expand Clause](/powersheet/reference/query-api/expand-clause) for full details.

## Complete YAML Example

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

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

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 |

***

**Related pages:** [Relationships](/powersheet/reference/data-model/relationships) | [Cardinality](/powersheet/reference/data-model/cardinality) | [Binding Syntax](/powersheet/reference/sheet-config/binding-syntax) | [Sources](/powersheet/reference/sheet-config/sources) | [Expand Clause](/powersheet/reference/query-api/expand-clause) | [Constraints](/powersheet/reference/data-model/constraints)

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