Binding Syntax

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.

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

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

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:

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

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:

sources:
  - id: user_needs
    query:
      from: UserNeed
    expand:
      - name: chapter

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

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)

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

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

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.

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

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

Columns — full column property reference
Sources — source query and expand configuration
Relationships — data model relationship definitions
Navigation Directions — direct and back direction reference
Cardinality — relationship cardinality rules
Multi-Item Columns — multi-item picker configuration
Views — view overrides using binding paths
Display Property — controlling display values for reference columns
Dynamic Value Expressions Reference — runtime expressions in column formulas

Binding Path Patterns

Binding Path Structure

Simple Property Binding

Scalar Navigation Binding (Many-to-One)

Reference Picker

Read-Only Property Access

Collection Navigation Binding (One-to-Many)

Association Entity Binding (Many-to-Many)

Source Expand (Two Levels)

Column Binding

Deep Multi-Level Binding

Binding Path Segments Reference

Binding and Source Alignment

Cardinality Summary

Column Properties Affecting Binding Behavior

Multi-Item vs. Expansion

Complete YAML Example

​Binding Path Patterns

​Binding Path Structure

​Simple Property Binding

​Scalar Navigation Binding (Many-to-One)

​Reference Picker

​Read-Only Property Access

​Collection Navigation Binding (One-to-Many)

​Association Entity Binding (Many-to-Many)

​Source Expand (Two Levels)

​Column Binding

​Deep Multi-Level Binding

​Binding Path Segments Reference

​Binding and Source Alignment

​Cardinality Summary

​Column Properties Affecting Binding Behavior

​Multi-Item vs. Expansion

​Complete YAML Example

​Related Pages

Binding Path Patterns

Binding Path Structure

Simple Property Binding

Scalar Navigation Binding (Many-to-One)

Reference Picker

Read-Only Property Access

Collection Navigation Binding (One-to-Many)

Association Entity Binding (Many-to-Many)

Source Expand (Two Levels)

Column Binding

Deep Multi-Level Binding

Binding Path Segments Reference

Binding and Source Alignment

Cardinality Summary

Column Properties Affecting Binding Behavior

Multi-Item vs. Expansion

Complete YAML Example

Related Pages