> ## 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. # Entity Types and Relationships > The data model in Nextedy POWERSHEET is built on two foundational concepts: **entity types** define the categories of objects in your traceability structure, and **relationships** define how those objects connect. 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

Last reviewed on {formatted}

; }; Think of the data model as an architect's blueprint. The blueprint defines which rooms exist (entity types) and how corridors connect them (relationships). The sheet then renders this blueprint as an interactive, navigable hierarchy where engineers can trace requirements to risks, link design decisions to test cases, and manage complex traceability chains -- all within a single configurable view. ## Entity Types: The Building Blocks An **entity type** represents a category of work item in your engineering process. In the data model YAML, entity types are declared under the `domainModelTypes` section. Each entity type maps to a Polarion work item type and declares which properties (fields) are visible in the sheet. ```yaml theme={null} domainModelTypes: UserNeed: polarionType: user_need properties: description: severity: component: ``` In this example, `UserNeed` is the entity type name used throughout Powersheet configuration. It maps to the `user_need` Polarion work item type and exposes three properties for display and editing in the sheet. Key aspects of entity types: | Property | Purpose | | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `polarionType` | Maps the domain entity to a Polarion work item type ID. If omitted, the entity type name itself is used as the Polarion type. | | `properties` | Declares which Polarion fields are exposed in the sheet. Each key maps to a work item custom field or built-in field. A null value means the property exists with default configuration. | | `constraints` | Optional rules for `load`, `create`, and `pick` behavior (see [Process Constraints](/powersheet/concepts/process-constraints)). | Entity type names in `domainModelTypes` must be single words without spaces or special characters. Use PascalCase: `UserNeed`, `SystemRequirement`, `DesignRequirement`. These names become the identifiers used in relationships, queries, and expansion paths throughout your configuration. ### Why Entity Types Matter Entity types serve as the translation layer between Polarion's flat work item storage and the structured data model that Powersheet uses to build hierarchical views. Without entity types, Powersheet would have no way to know that a `user_need` work item type should appear as a top-level requirement, or that a `hazard` work item type represents a risk that traces back to a system requirement. This translation layer is what enables Powersheet to present the same underlying Polarion data in fundamentally different ways. A requirements traceability matrix, a risk analysis sheet, and a design verification view can all draw from the same project data -- the data model defines which entity types participate and how they relate. ### Multiple Polarion Types per Entity A single entity type can map to multiple Polarion work item types. The `polarionType` property accepts either a single string or an array: ```yaml theme={null} domainModelTypes: Requirement: polarionType: - sys_req - des_req ``` When an entity maps to multiple types, the sheet handles type selection during creation and filtering during queries. This is useful when you want to treat several related Polarion types as a single logical category in your data model -- for example, grouping system requirements and design requirements under a unified `Requirement` entity type. ### Entity Type Properties Properties declared on an entity type control which fields are visible and editable in the sheet. Each property key corresponds to a Polarion work item field (built-in or custom). When a property is declared with a null value, it uses default configuration: ```yaml theme={null} domainModelTypes: SystemRequirement: polarionType: sys_req properties: description: severity: priority: verificationMethod: ``` Properties do more than expose fields. They become the vocabulary that columns, formatters, and queries use to reference data. When you configure a column with a binding path like `systemRequirements.systemRequirement.severity`, you are navigating through relationships and accessing a declared property. If `severity` is not declared in the entity type's `properties`, it will not be available in the sheet. ## Relationships: The Connections **Relationships** define how entity types connect to each other. Each relationship specifies a source and target entity type, a cardinality pattern, a storage mechanism, and navigation properties that enable traversal in both directions. ```yaml theme={null} relationships: - from: UserNeed to: SystemRequirement cardinality: many-to-many storage: linkedWorkItems linkRole: decomposes direct: name: systemRequirements back: name: userNeeds ``` diagram Every relationship has two sides: * **`direct`** -- The forward navigation property, created on the `from` entity type. In the example above, navigating from `UserNeed` to its related `SystemRequirement` items uses the property named `systemRequirements`. * **`back`** -- The reverse navigation property, created on the `to` entity type. Navigating from `SystemRequirement` back to its originating `UserNeed` items uses the property named `userNeeds`. This bidirectional design means you can build sheets that start from either end of a relationship. A requirements traceability matrix might start from `UserNeed` and expand into `SystemRequirement` items (using the `direct` navigation). A reverse traceability view might start from `SystemRequirement` and expand back to `UserNeed` items (using the `back` navigation). By convention, singular names (like `chapter`) indicate many-to-one relationships (one target), while plural names (like `systemRequirements`) indicate one-to-many or many-to-many relationships (multiple targets). This naming convention is not enforced by the system but makes configurations easier to read and maintain. ## Cardinality: How Many Can Connect **Cardinality** defines the multiplicity of a relationship -- how many instances of each entity type can participate. Powersheet supports three cardinality patterns, and each one determines how the relationship appears in the sheet, how sources expand data, and how columns bind to navigation properties. ### Many-to-One (N:1) Each instance of the `from` entity belongs to exactly one instance of the `to` entity. This is the simplest relationship pattern. **Example:** Each `UserNeed` belongs to exactly one `Chapter`. ```yaml theme={null} relationships: - from: UserNeed to: Chapter cardinality: many-to-one storage: linkedWorkItems linkRole: parent direct: name: chapter back: name: userNeeds ``` In the sheet, a many-to-one relationship renders as a **single-value reference picker**. The `chapter` column shows one value and allows selecting a different `Chapter` entity. You can also display properties of the referenced entity using dot notation: ```yaml theme={null} columns: chapter: title: Chapter display: title list: search: - title chapter.title: title: Chapter Title isReadOnly: true ``` The column `chapter` provides a picker for selecting the parent chapter. The column `chapter.title` displays the title of the linked chapter as a read-only field. ### One-to-Many (1:N) Each instance of the `to` entity has multiple instances of the `from` entity. This is the reverse view of a many-to-one relationship -- same underlying link, different perspective. **Example:** Each `Chapter` has multiple child `UserNeed` items. ```yaml theme={null} sources: - id: chapters query: from: Chapter expand: - name: userNeeds ``` In the sheet, a one-to-many relationship creates **child rows** -- a new hierarchy level that expands beneath the parent row. The `expand` clause in the source configuration tells Powersheet to load the related items and nest them under their parent. ```yaml theme={null} columns: title: title: Chapter hasFocus: true userNeeds: title: User Need hasFocus: true ``` The `userNeeds` column represents the expanded child level. No dot notation is needed because the expand directly opens the child level in the sheet hierarchy. ### Many-to-Many (M:N) Both sides of the relationship can have multiple instances. This is the most complex pattern and uses an **association entity** as an intermediate layer. **Example:** `UserNeed` items linked to multiple `SystemRequirement` items and vice versa. ```yaml theme={null} sources: - id: user_needs query: from: UserNeed expand: - name: systemRequirements expand: - name: systemRequirement ``` The source expand is two levels deep: first `systemRequirements` (the association collection), then `systemRequirement` (the actual target entity). Column bindings use dot notation to reach through the association: ```yaml theme={null} columns: title: title: Title hasFocus: true systemRequirements.systemRequirement: title: System Requirement list: search: - objectId - title createNew: true systemRequirements.systemRequirement.title: title: SysReq Title hasFocus: true ``` The column `systemRequirements.systemRequirement` acts as a **multi-item reference picker**, allowing users to link multiple system requirements to a single user need. ### Cardinality Summary | Cardinality | Source expand | Column binding | UI behavior | | ----------- | ------------------------------------------------------------- | -------------------------------------- | -------------------------------- | | **N:1** | `- name: chapter` | `chapter`, `chapter.title` | Single-value reference picker | | **1:N** | `- name: userNeeds` | `userNeeds` | Child rows (new hierarchy level) | | **M:N** | `- name: systemRequirements` then `- name: systemRequirement` | `systemRequirements.systemRequirement` | Multi-item reference picker | A common mistake is to use a single-level expand for many-to-many relationships. The association entity is an intermediate layer that must be expanded separately. If you write `expand: [name: systemRequirements]` without the nested expand to `systemRequirement`, the sheet will show the association objects rather than the target entities. ## Storage Mechanisms The `storage` property determines how Powersheet persists relationships in Polarion. The only supported storage mechanism is `linkedWorkItems`, which uses Polarion's native link mechanism. The relationship is stored as a typed link between work items, identified by the `linkRole` property. The `linkRole` must match a link role defined in the Polarion project configuration. Common link roles include `parent`, `refines`, `decomposes`, `verifies`, and `mitigates`. ## The Three-Layer Connection Entity types and relationships form just the first layer. Understanding how the three configuration layers connect is essential for building working sheets: 1. **Data model** -- Defines entity types and relationships with navigation property names 2. **Sources** -- Define how to query and expand those relationships using the navigation property names 3. **Columns** -- Define how to display the resulting data using binding paths that follow the navigation property chain diagram The navigation property names defined in `direct` and `back` are the glue. The same name appears in the data model relationship, the source `expand` clause, and the column binding path. If any layer uses a different name, the chain breaks. For a deeper exploration of how sources connect to data model navigation properties, see [Source Configuration](/powersheet/concepts/source-configuration). For the reference of all relationship properties, see [Data Model Reference](/powersheet/reference/data-model/index). ## A Complete Example Bringing all concepts together, here is a minimal but complete data model that demonstrates entity types, relationships across multiple cardinality patterns, and the standard RTM entities: ```yaml theme={null} domainModelTypes: Chapter: polarionType: heading UserNeed: polarionType: user_need properties: description: severity: SystemRequirement: polarionType: sys_req properties: description: severity: DesignRequirement: polarionType: des_req properties: description: relationships: - from: UserNeed to: Chapter cardinality: many-to-one storage: linkedWorkItems linkRole: parent direct: name: chapter back: name: userNeeds - from: SystemRequirement to: UserNeed cardinality: many-to-many storage: linkedWorkItems linkRole: decomposes direct: name: userNeeds back: name: systemRequirements ``` This model defines four entity types and two relationships. `Chapter` entities group `UserNeed` items (many-to-one), while `SystemRequirement` and `UserNeed` share a many-to-many traceability link. Each relationship declares both `direct` and `back` navigation properties, enabling sheets to traverse the hierarchy from either direction. New users should begin with a minimal single-entity configuration and extend gradually. Jumping straight to complex multi-entity models with multiple relationship types leads to hard-to-diagnose errors. Add one entity type and one relationship at a time, verifying each addition works correctly in the sheet before adding the next. ## Common Misconceptions **"Every entity type needs properties"** -- Not true. An entity type can be declared with no properties at all. It will still participate in relationships and appear in the sheet hierarchy. Properties only need to be declared for fields you want to expose as columns. **"Relationships are always bidirectional"** -- While Powersheet creates navigation properties in both directions (`direct` and `back`), not every sheet needs to use both. A sheet starting from `UserNeed` may only use the `direct` navigation to `SystemRequirement` without ever traversing the `back` direction. **"The second linked column works the same as the first"** -- When a sheet has two different entity types linked to the same parent (for example, design outputs and design verifications both linked to system requirements), the second linked column must be declared with `multiItem: true` in the sheet configuration. This is a non-obvious requirement that frequently blocks new users during initial setup. See [Multi-Item Columns](/powersheet/reference/sheet-config/multi-item-columns) for details. ## Next Steps * [Navigation Properties](/powersheet/concepts/navigation-properties) -- How navigation properties enable expansion paths and column bindings * [Link Cardinality](/powersheet/concepts/link-cardinality) -- Detailed cardinality rules and their impact on sheet behavior * [Data Model vs Sheet Configuration](/powersheet/concepts/data-model-vs-sheet-config) -- How data model and sheet configuration complement each other * [Configure a Relationship](/powersheet/guides/data-model/configure-relationship) -- Step-by-step guide to adding relationships