Skip to main content
The domain 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.

​
Binding Path Patterns

PatternTypeExampleDescription
<property>SimpletitleBinds to a direct property of the root entity type
<nav>Scalar referencechapterNavigates a many-to-one relationship (picker column)
<nav>.<property>One-levelchapter.titleNavigates one relationship and reads a property
<nav>.<entity>Collection entitysystemRequirements.systemRequirementNavigates through an association entity (new level or multi-item)
<nav>.<entity>.<property>Two-levelsystemRequirements.systemRequirement.titleNavigates through a relationship to a child entity property
<nav>.<entity>.<nav>.<entity>.<property>Multi-levelsystemRequirements.systemRequirement.designRequirements.designRequirement.titleDeep navigation through multiple relationship levels

​
Binding Path Structure

diagram

​
Simple Property Binding

Binds directly to a property of the root entity type defined in sources[].query.from. No navigation is involved. 
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 domain model. The source query from: UserNeed determines the root context.
ElementValueMeaning
BindingtitleRoot entity property
Source neededfrom: UserNeedRoot query only
Expand neededNoneNo relationship traversal
UI behaviorDirect editEditable cell bound to root property

​
Scalar Navigation Binding (Many-to-One)

When the domain 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: 
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: 
columns:
  chapter.title:
    title: Chapter Title
    isReadOnly: true
ElementValueMeaning
BindingchapterScalar reference picker (N:1)
Bindingchapter.titleRead-only display of referenced property
Source expand- name: chapterSingle-level expand
Domain modelcardinality: many-to-one, direct: { name: chapter }Defines the navigation
Source configuration: 
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. 
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: 
sources:
  - id: chapters
    query:
      from: Chapter
    expand:
      - name: userNeeds
ElementValueMeaning
BindinguserNeedsCollection navigation (1:N, creates child rows)
Source expand- name: userNeedsSingle-level expand
Domain modelback: { name: userNeeds }Reverse of the many-to-one relationship
UI behaviorChild rowsExpands 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)

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

columns:
  systemRequirements.systemRequirement:
    title: System Requirement
    list:
      search:
        - objectId
        - title
      createNew: true
  systemRequirements.systemRequirement.title:
    title: SysReq Title
    hasFocus: true
  systemRequirements.systemRequirement.severity:
    title: Severity
    width: 100
ElementValueMeaning
BindingsystemRequirements.systemRequirementAssociation entity reference (M:N)
BindingsystemRequirements.systemRequirement.titleProperty of the target entity
Source expandTwo levels: systemRequirements then systemRequirementTraverses association
Domain modelcardinality: many-to-many, back: { name: systemRequirements }Defines the relationship
UI behaviorMulti-item reference pickerPicker with create-new support

​
Deep Multi-Level Binding

Navigation paths can chain multiple relationships to reach deeply nested entities. Each additional relationship adds another <nav>.<entity> segment. 
columns:
  systemRequirements.systemRequirement.designRequirements.designRequirement.title:
    title: Design Requirement
    hasFocus: true
  systemRequirements.systemRequirement.designRequirements.designRequirement.description:
    title: DR Description
    width: 180
Corresponding source expand: 
sources:
  - id: user_needs
    query:
      from: UserNeed
    expand:
      - name: systemRequirements
        expand:
          - name: systemRequirement
            expand:
              - name: designRequirements
                expand:
                  - name: designRequirement
Each additional expansion level increases the amount of data loaded from the server. Limit deep navigation to three or four levels for optimal performance.

​
Binding Path Segments Reference

Each segment of a dot-separated binding path corresponds to a specific element from the domain model or entity type definition.
Segment PositionResolves ToSource
First segment (e.g., systemRequirements)Navigation property namedirect.name or back.name from a relationship
Second segment (e.g., systemRequirement)Target entity name (singular)Entity type from domainModelTypes
Subsequent pairsRepeat of nav property + entityAdditional relationships in the chain
Final segment (e.g., title)Property nameproperties 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 BindingRequired Source ExpandRelationship
titleNone (root property)Direct property
chapter- name: chapterN:1 scalar
chapter.title- name: chapterN:1 property access
userNeeds- name: userNeeds1:N collection
systemRequirements.systemRequirementsystemRequirements > systemRequirementM:N association
systemRequirements.systemRequirement.titlesystemRequirements > systemRequirementM:N property
Navigation property names follow the domain 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.

​
Cardinality Summary

CardinalityDomain ModelSource ExpandColumn BindingUI Behavior
N:1cardinality: many-to-one, direct: { name: chapter }- name: chapterchapter or chapter.titleSingle-value reference picker
1:NReverse of N:1, back: { name: userNeeds }- name: userNeedsuserNeedsChild rows (new grid level)
M:Ncardinality: many-to-many, back: { name: systemRequirements }- name: systemRequirements > - name: systemRequirementsystemRequirements.systemRequirementMulti-item reference picker

​
Column Properties Affecting Binding Behavior

These column properties interact directly with how the binding path resolves and displays data.
PropertyTypeDefaultDescription
displaystringidWhich property of the referenced entity to show in a scalar reference column (N:1). Common values: title, titleOrName, or a custom property path
multiItembooleanfalseWhen true, treats a collection binding as a multi-item picker instead of expanding to child rows
listobjectnullConfigures the picker dropdown for reference columns
list.searchstring[]—Array of property names searchable in the picker dropdown
list.createNewbooleanfalseEnables creating new entities directly from the picker
isReadOnlybooleanfalseForces the column to read-only regardless of permissions. Commonly used on <nav>.<property> bindings
hasFocusbooleanfalseMarks 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.
ConfigurationBindingBehavior
Default (no multiItem)systemRequirements.systemRequirementCreates child rows with a new grid level
multiItem: truesystemRequirements.systemRequirementRenders as a multi-item picker column without creating a new level
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.

​
Complete YAML Example

A full sheet configuration demonstrating all binding patterns with the standard RTM entity hierarchy (UserNeed > SystemRequirement > DesignRequirement): 
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
      createNew: true
  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
Code: PowersheetConfig.d.ts (configuration type definitions), whole_rtm.template.yaml (RTM configuration template), document.ts (document DTO types), document.ts (domain types with column binding class) Reference: Sheet configuration (Confluence), Model / Source / Columns: Cardinality Reference (Confluence)