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

# Binding Syntax

> In a Nextedy POWERSHEET sheet configuration, the **binding path** (also called **column key**) is the YAML key that defines each column in the `columns` section.

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

<Tip title="Binding paths connect three layers">
  The data model defines entity types and relationships. Sources define how to query and expand those relationships. Column binding paths define how to display the resulting data. All three layers are connected through navigation property names.
</Tip>

***

## Binding Path Patterns

| Pattern                                    | Type              | Example                                                                           | Description                                                       |
| ------------------------------------------ | ----------------- | --------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| `<property>`                               | Simple            | `title`                                                                           | Binds to a direct property of the root entity type                |
| `<nav>`                                    | Scalar reference  | `chapter`                                                                         | Navigates a many-to-one relationship (picker column)              |
| `<nav>.<property>`                         | One-level         | `chapter.title`                                                                   | Navigates one relationship and reads a property                   |
| `<nav>.<entity>`                           | Collection entity | `systemRequirements.systemRequirement`                                            | Navigates through an association entity (new level or multi-item) |
| `<nav>.<entity>.<property>`                | Two-level         | `systemRequirements.systemRequirement.title`                                      | Navigates through a relationship to a child entity property       |
| `<nav>.<entity>.<nav>.<entity>.<property>` | Multi-level       | `systemRequirements.systemRequirement.designRequirements.designRequirement.title` | Deep navigation through multiple relationship levels              |

***

## Binding Path Structure

<Frame>
  <img src="https://mintcdn.com/none-17b4493f/-WiVljKlDztH36bB/powersheet/diagrams/reference/sheet-config/binding-syntax/diagram-1.svg?fit=max&auto=format&n=-WiVljKlDztH36bB&q=85&s=664084f9cb02abe3e0fee5c495cba65d" alt="diagram" style={{ width: "520px", maxWidth: "100%" }} width="520" height="155" data-path="powersheet/diagrams/reference/sheet-config/binding-syntax/diagram-1.svg" />
</Frame>

***

## Simple Property Binding

Binds directly to a property of the root entity type defined in `sources[].query.from`. No navigation is involved.

```yaml theme={null}
columns:
  id:
    title: ID
    width: 80
    isReadOnly: true
  title:
    title: User Need
    width: 200
    hasFocus: true
  outlineNumber:
    title: "#"
    width: 80
  severity:
    title: Severity
    width: 100
  description:
    title: Description
    width: 140
```

**Resolution:** Each key (`id`, `title`, `severity`, etc.) maps to a property defined in the `properties` section of the root entity type in the data model. The source query `from: UserNeed` determines the root context.

| Element       | Value            | Meaning                              |
| ------------- | ---------------- | ------------------------------------ |
| Binding       | `title`          | Root entity property                 |
| Source needed | `from: UserNeed` | Root query only                      |
| Expand needed | None             | No relationship traversal            |
| UI behavior   | Direct edit      | Editable cell bound to root property |

***

## Scalar Navigation Binding (Many-to-One)

When the data model defines a `many-to-one` relationship, the `direct` navigation property name resolves to a single referenced entity (scalar reference). Two binding forms apply.

### Reference Picker

Use the navigation property name alone to create a reference picker column:

```yaml theme={null}
columns:
  chapter:
    title: Chapter
    display: title
    list:
      search:
        - title
```

The `display` property controls which field of the referenced entity appears in the cell. The `list.search` array defines which fields are searchable in the picker dropdown.

### Read-Only Property Access

Append a property name to the navigation property with dot notation to display a specific field from the referenced entity:

```yaml theme={null}
columns:
  chapter.title:
    title: Chapter Title
    isReadOnly: true
```

| Element       | Value                                                   | Meaning                                  |
| ------------- | ------------------------------------------------------- | ---------------------------------------- |
| Binding       | `chapter`                                               | Scalar reference picker (N:1)            |
| Binding       | `chapter.title`                                         | Read-only display of referenced property |
| Source expand | `- name: chapter`                                       | Single-level expand                      |
| Data model    | `cardinality: many-to-one`, `direct: { name: chapter }` | Defines the navigation                   |

**Source configuration:**

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

***

## Collection Navigation Binding (One-to-Many)

The `back` direction of a many-to-one relationship produces a one-to-many collection. The navigation property name creates a new hierarchical level in the sheet.

```yaml theme={null}
columns:
  title:
    title: Chapter
    hasFocus: true
  userNeeds:
    title: User Need Title
    hasFocus: true
```

No dot notation is needed. The expand in the source directly opens the child level.

**Source configuration:**

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

| Element       | Value                       | Meaning                                         |
| ------------- | --------------------------- | ----------------------------------------------- |
| Binding       | `userNeeds`                 | Collection navigation (1:N, creates child rows) |
| Source expand | `- name: userNeeds`         | Single-level expand                             |
| Data model    | `back: { name: userNeeds }` | Reverse of the many-to-one relationship         |
| UI behavior   | Child rows                  | Expands into a new grid level                   |

***

## Association Entity Binding (Many-to-Many)

Many-to-many relationships use an **association entity** between the two types. Both the source expand and the column binding require two levels of navigation.

### Source Expand (Two Levels)

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

The first level (`systemRequirements`) navigates to the association entity. The second level (`systemRequirement`) navigates from the association to the target entity.

### Column Binding

```yaml theme={null}
columns:
  systemRequirements.systemRequirement:
    title: System Requirement
    list:
      search:
        - objectId
        - title
  systemRequirements.systemRequirement.title:
    title: SysReq Title
    hasFocus: true
  systemRequirements.systemRequirement.severity:
    title: Severity
    width: 100
```

| Element       | Value                                                             | Meaning                                |
| ------------- | ----------------------------------------------------------------- | -------------------------------------- |
| Binding       | `systemRequirements.systemRequirement`                            | Association entity reference (M:N)     |
| Binding       | `systemRequirements.systemRequirement.title`                      | Property of the target entity          |
| Source expand | Two levels: `systemRequirements` then `systemRequirement`         | Traverses association                  |
| Data model    | `cardinality: many-to-many`, `back: { name: systemRequirements }` | Defines the relationship               |
| UI behavior   | Multi-item reference picker                                       | Picker bound to the association target |

***

## Deep Multi-Level Binding

Navigation paths can chain multiple relationships to reach deeply nested entities. Each additional relationship adds another `<nav>.<entity>` segment.

```yaml theme={null}
columns:
  systemRequirements.systemRequirement.designRequirements.designRequirement.title:
    title: Design Requirement
    hasFocus: true
  systemRequirements.systemRequirement.designRequirements.designRequirement.description:
    title: DR Description
    width: 180
```

**Corresponding source expand:**

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

<Warning title="Performance consideration">
  Each additional expansion level increases the amount of data loaded from the server. Limit deep navigation to three or four levels for optimal performance.
</Warning>

***

## Binding Path Segments Reference

Each segment of a dot-separated binding path corresponds to a specific element from the data model or entity type definition.

| Segment Position                           | Resolves To                     | Source                                                                                             |
| ------------------------------------------ | ------------------------------- | -------------------------------------------------------------------------------------------------- |
| First segment (e.g., `systemRequirements`) | Navigation property name        | `direct.name` or `back.name` from a [relationship](/powersheet/reference/data-model/relationships) |
| Second segment (e.g., `systemRequirement`) | Target entity name (singular)   | Entity type from `domainModelTypes`                                                                |
| Subsequent pairs                           | Repeat of nav property + entity | Additional relationships in the chain                                                              |
| Final segment (e.g., `title`)              | Property name                   | `properties` section of the target entity type                                                     |

***

## Binding and Source Alignment

The column binding path must exactly mirror the expansion hierarchy defined in the source configuration. Mismatches produce empty or missing columns.

| Column Binding                               | Required Source Expand                     | Relationship        |
| -------------------------------------------- | ------------------------------------------ | ------------------- |
| `title`                                      | None (root property)                       | Direct property     |
| `chapter`                                    | `- name: chapter`                          | N:1 scalar          |
| `chapter.title`                              | `- name: chapter`                          | N:1 property access |
| `userNeeds`                                  | `- name: userNeeds`                        | 1:N collection      |
| `systemRequirements.systemRequirement`       | `systemRequirements` > `systemRequirement` | M:N association     |
| `systemRequirements.systemRequirement.title` | `systemRequirements` > `systemRequirement` | M:N property        |

<Note title="Naming convention">
  Navigation property names follow the data model exactly. Collection properties use plural names (e.g., `systemRequirements`). Entity references in association paths use singular names (e.g., `systemRequirement`). Property names match the `properties` section of the entity type definition.
</Note>

***

## Cardinality Summary

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

***

## Column Properties Affecting Binding Behavior

These column properties interact directly with how the binding path resolves and displays data.

| Property         | Type      | Default | Description                                                                                                                                          |
| ---------------- | --------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `display`        | string    | `id`    | Which property of the referenced entity to show in a scalar reference column (N:1). Common values: `title`, `titleOrName`, or a custom property path |
| `multiItem`      | boolean   | `false` | When `true`, treats a collection binding as a multi-item picker instead of expanding to child rows                                                   |
| `list`           | object    | `null`  | Configures the picker dropdown for reference columns                                                                                                 |
| `list.search`    | string\[] | --      | Array of property names searchable in the picker dropdown                                                                                            |
| `list.createNew` | boolean   | `false` | Enables creating new entities directly from the picker                                                                                               |
| `isReadOnly`     | boolean   | `false` | Forces the column to read-only regardless of permissions. Commonly used on `<nav>.<property>` bindings                                               |
| `hasFocus`       | boolean   | `false` | Marks the primary focus column for a given hierarchy level. If multiple levels exist, each can have its own `hasFocus` column                        |

***

## Multi-Item vs. Expansion

A collection navigation property can either expand into child rows (default) or render as a multi-item picker. The `multiItem` property controls this behavior.

| Configuration            | Binding                                | Behavior                                                           |
| ------------------------ | -------------------------------------- | ------------------------------------------------------------------ |
| Default (no `multiItem`) | `systemRequirements.systemRequirement` | Creates child rows with a new grid level                           |
| `multiItem: true`        | `systemRequirements.systemRequirement` | Renders as a multi-item picker column without creating a new level |

```yaml theme={null}
columns:
  systemRequirements.systemRequirement:
    title: Linked SysReqs
    multiItem: true
    display: title
    list:
      search:
        - objectId
        - title
```

For full details on multi-item behavior, see [Multi-Item Columns](/powersheet/reference/sheet-config/multi-item-columns).

***

## Complete YAML Example

A full sheet configuration demonstrating all binding patterns with the standard RTM entity hierarchy (`UserNeed` > `SystemRequirement` > `DesignRequirement`):

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

columns:
  # Simple property binding (root entity)
  id:
    title: ID
    width: 80
    isReadOnly: true
  title:
    title: User Need
    width: 200
    hasFocus: true
  severity:
    title: Severity
    width: 100

  # Scalar reference binding (N:1)
  chapter:
    title: Chapter
    display: title
    list:
      search:
        - title

  # Scalar property access (N:1 read-only)
  chapter.title:
    title: Chapter Title
    isReadOnly: true

  # Association entity binding (M:N)
  systemRequirements.systemRequirement:
    title: System Requirement
    list:
      search:
        - objectId
        - title
  systemRequirements.systemRequirement.title:
    title: SysReq Title
    width: 180
    hasFocus: true
  systemRequirements.systemRequirement.severity:
    title: SysReq Severity
    width: 100

  # Deep multi-level binding (M:N > M:N)
  systemRequirements.systemRequirement.designRequirements.designRequirement:
    title: Design Requirement
    list:
      search:
        - objectId
        - title
  systemRequirements.systemRequirement.designRequirements.designRequirement.title:
    title: DesReq Title
    width: 180
    hasFocus: true
  systemRequirements.systemRequirement.designRequirements.designRequirement.description:
    title: DesReq Description
    width: 200

views:
  Without Design:
    columns:
      systemRequirements.systemRequirement.designRequirements.designRequirement:
        visible: false
      systemRequirements.systemRequirement.designRequirements.designRequirement.title:
        visible: false
      systemRequirements.systemRequirement.designRequirements.designRequirement.description:
        visible: false

sortBy:
  - columnId: severity
    direction: desc
```

***

## Related Pages

* [Columns](/powersheet/reference/sheet-config/columns) -- full column property reference
* [Sources](/powersheet/reference/sheet-config/sources) -- source query and expand configuration
* [Relationships](/powersheet/reference/data-model/relationships) -- data model relationship definitions
* [Navigation Directions](/powersheet/reference/data-model/navigation-directions) -- `direct` and `back` direction reference
* [Cardinality](/powersheet/reference/data-model/cardinality) -- relationship cardinality rules
* [Multi-Item Columns](/powersheet/reference/sheet-config/multi-item-columns) -- multi-item picker configuration
* [Views](/powersheet/reference/sheet-config/views) -- view overrides using binding paths
* [Display Property](/powersheet/reference/sheet-config/display-property) -- controlling display values for reference columns
* [Dynamic Value Expressions Reference](/powersheet/reference/sheet-config/dynamic-expressions) -- runtime expressions in column formulas

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