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
Data model does not load	`cardinality` set to `one-to-many`, `one-to-one`, or another unsupported value	Step 7: Replace Unsupported Cardinality Values

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

Case sensitivity mattersEntity 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

Missing navigation namesIf 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 requires two expand levelsMany-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.

Use Polarion link role IDs, not display namesThe 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
1:N (`back` side of `many-to-one`)	`- name: userNeeds`	`userNeeds`	Child rows (new sheet level)
`many-to-many`	`- name: systemRequirements` then `- name: systemRequirement`	`systemRequirements.systemRequirement`	Multi-item reference picker

Cardinality affects column behaviorA many-to-one column displays a single-value reference picker. A 1:N expand on the back side of a many-to-one relationship 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

Start with a single-item configurationWhen 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.

Replace Unsupported Cardinality Values

If the data model does not load and a relationship declares cardinality: one-to-many, cardinality: one-to-one, or any other value besides many-to-one and many-to-many, the unsupported value is the cause. Powersheet supports only those two values, and any other value stops the whole data model from loading.To give one parent many children, declare the relationship as many-to-one from the child side: swap from and to, and swap the direct and back names. If each parent holds the links to its children in Polarion, use many-to-many with the parent as from instead.

relationships:
  # WRONG - one-to-many is not a supported value
  # - from: UserNeed
  #   to: SystemRequirement
  #   cardinality: one-to-many
  #   direct:
  #     name: systemRequirements
  #   back:
  #     name: userNeed

  # CORRECT - many-to-one from the child side
  - from: SystemRequirement
    to: UserNeed
    cardinality: many-to-one
    storage: linkedWorkItems
    linkRole: refines
    direct:
      name: userNeed
    back:
      name: systemRequirements

UserNeed keeps systemRequirements as its collection navigation property, so source expands and column bindings that start from UserNeed keep the same name. See One-to-Many (1:N) for the full pattern.

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