Fix Relationship Errors - Nextedy Documentation

Symptom Quick Reference

Use this table to jump to the right fix based on the error you are seeing:

Symptom	Likely Cause	Jump To
Sheet fails to load after saving the data model	Invalid `from` or `to` entity reference	Step 1: Verify Entity Type References
Navigation columns appear empty	Missing or wrong `direct`/`back` name	Step 2: Check Navigation Property Names
Expansion path produces no child rows	Navigation name mismatch between model and sources	Step 3: Align Sources with Navigation Names
Links not saved to Polarion	Invalid `linkRole` value	Step 4: Verify the Link Role
Wrong column behavior (multi vs. single)	Cardinality does not match the actual relationship	Step 5: Validate Cardinality
Second linked column shows nothing	Missing `multiItem: true` on the column	Step 6: Fix Multi-Item Column Declarations

Verify Entity Type References

Every relationship must reference valid entity type names in its from and to fields. These names must exactly match keys defined under domainModelTypes, including capitalization.

domainModelTypes:
  UserNeed:
    polarionType: user_need
    properties:
      description:
      severity:
  SystemRequirement:
    polarionType: sys_req
    properties:
      description:
      severity:

relationships:
  - from: UserNeed              # Must match a domainModelTypes key exactly
    to: SystemRequirement       # Must match a domainModelTypes key exactly
    cardinality: many-to-many
    storage: linkedWorkItems
    linkRole: decomposes
    direct:
      name: userNeeds
    back:
      name: systemRequirements

Entity type names are case-sensitive. systemRequirement and SystemRequirement are different values. If the from value does not match any domainModelTypes key, the source side of the relationship is broken. If the to value is wrong, the target side is broken. Double-check exact capitalization in both locations.

Check Navigation Property Names

The direct and back sections each contain a name field that creates a navigation property on the respective entity type. These navigation property names are what you use in column binding paths and source expansion paths throughout the sheet configuration.

direct.name — creates a forward navigation property on the from entity type (navigates toward the to entity)
back.name — creates a reverse navigation property on the to entity type (navigates back toward the from entity)

relationships:
  - from: UserNeed
    to: SystemRequirement
    cardinality: many-to-many
    storage: linkedWorkItems
    linkRole: decomposes
    direct:
      name: userNeeds              # Property on SystemRequirement pointing back to UserNeed
    back:
      name: systemRequirements     # Property on UserNeed pointing forward to SystemRequirement

If either direct or back is missing its name field, the corresponding navigation property will not be created. Any column or expansion path that references that property name will silently return no data.

Align Sources with Navigation Names

The expand entries in your sheet configuration sources must exactly match the navigation property names defined by direct.name or back.name in the data model. A mismatch here is one of the most common causes of empty expansion results.Many-to-one (N:1) — single-level expand:

# Data model: UserNeed -> Chapter, direct.name = "chapter"
sources:
  - id: user_needs
    query:
      from: UserNeed
    expand:
      - name: chapter           # Must match direct.name exactly

One-to-many (1:N) — collection expand:

# Data model: Chapter <- UserNeed, back.name = "userNeeds"
sources:
  - id: chapters
    query:
      from: Chapter
    expand:
      - name: userNeeds         # Must match back.name exactly

Many-to-many (M:N) — two-level expand through association:

# Data model: UserNeed <-> SystemRequirement, back.name = "systemRequirements"
sources:
  - id: user_needs
    query:
      from: UserNeed
    expand:
      - name: systemRequirements          # Association level
        expand:
          - name: systemRequirement       # Target entity level

Many-to-many relationships use an association entity between the two types. The source expand must go two levels deep: first the collection navigation property (e.g., systemRequirements), then the target entity within the association (e.g., systemRequirement). Forgetting the second level is a frequent cause of empty columns.

Verify the Link Role

The linkRole must match a link role ID defined in your Polarion project configuration, not its display name.

relationships:
  - from: UserNeed
    to: SystemRequirement
    cardinality: many-to-many
    storage: linkedWorkItems
    linkRole: decomposes          # Polarion link role ID, not display name
    direct:
      name: userNeeds
    back:
      name: systemRequirements

To find valid link role IDs, go to Administration > Work Items > Link Roles in Polarion. The ID column shows the value to use in your data model YAML.

The linkRole value is the link role ID (e.g., decomposes, parent), not the display name (e.g., “Decomposes”, “Has Parent”). If the link role ID does not exist in the project, relationships will not persist when users save changes in the sheet.

Validate Cardinality

The cardinality value must match the actual relationship between your entity types. Using the wrong cardinality causes incorrect UI behavior — columns that should allow multiple selections only show one value, or vice versa.

Cardinality	Source Expand	Column Binding	UI Behavior
`many-to-one`	`- name: chapter`	`chapter`, `chapter.title`	Single-value reference picker
`one-to-many`	`- name: userNeeds`	`userNeeds`	Child rows (new sheet level)
`many-to-many`	`- name: systemRequirements` then `- name: systemRequirement`	`systemRequirements.systemRequirement`	Multi-item reference picker

A many-to-one column displays a single-value reference picker. A one-to-many expand creates child rows in the sheet. A many-to-many column uses a multi-item picker with association entity binding. If you set the wrong cardinality, the sheet may render but users will encounter errors when trying to edit or save relationships.

Fix Multi-Item Column Declarations

When a parent entity links to multiple work item types (for example, a SystemRequirement linked to both DesignRequirement and DesignVerification), the second linked column must include multiItem: true in the sheet configuration. This is a non-obvious requirement that frequently blocks first-time configurations.

columns:
  designRequirements.designRequirement:
    title: Design Requirement
    list:
      search:
        - title
  designVerifications.designVerification:
    title: Design Verification
    multiItem: true               # Required for the second linked entity column
    list:
      search:
        - title

When setting up a new sheet, start with the simplest possible configuration — one entity type, one relationship. Add additional linked columns incrementally. This approach makes it much easier to isolate which relationship definition is causing errors.

Validate the Complete Configuration Chain

After making corrections, verify the full chain from data model through sources to columns:

Data model — confirm from/to match domainModelTypes keys, linkRole is a valid Polarion link role ID, and both direct.name and back.name are present
Sources — confirm each expand name matches a navigation property name from the data model, and many-to-many expands have two levels
Columns — confirm column binding paths use the correct dot-notation from the expand chain, and multiItem: true is set where needed
Storage — confirm storage: linkedWorkItems is used for Polarion link-based relationships

Verification

After correcting the relationship configuration:

Save the data model YAML in Administration > Nextedy Powersheet > Data Models
Open a powersheet document that uses this data model
Expand a row with related entities
You should now see child entities appearing correctly under the expansion path, and the reference picker columns displaying valid choices

​Symptom Quick Reference

​Verification

​See Also

Symptom Quick Reference

Verification

See Also