> ## 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. # Data Model vs Sheet Configuration > One of the most important design decisions in Nextedy POWERSHEET is the separation between the **data model** and the **sheet configuration**. 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}

; }; This page explains what each file does, why they are separate, and how they connect at runtime to produce the sheets you see in Siemens Polarion ALM. ## Two files, two concerns Think of the data model as a **blueprint** and the sheet configuration as a **floor plan**. The blueprint defines the structural elements that exist -- walls, beams, doors -- while the floor plan decides which rooms to show, how to arrange the furniture, and what view each window offers. You can redesign a room without re-engineering the building, and you can reuse the same structural elements in many different room layouts. At its simplest, the distinction is: | | Data Model | Sheet Configuration | | ------------------ | ----------------------------------------------------- | -------------------------------------------------------------- | | **Purpose** | Defines what data exists | Defines how data is displayed | | **Contains** | Entity types, relationships, constraints | Columns, sources, views, formatters | | **YAML root keys** | `domainModelTypes`, `relationships` | `columns`, `sources`, `views`, `formatters` | | **Managed in** | **Administration > Nextedy Powersheet > Data Models** | **Administration > Nextedy Powersheet > Sheet Configurations** | | **Scope** | Project or Global | Project or Global | The data model describes the **structure** of your data: what entity types exist, what properties they have, how they relate to each other, and what Polarion work item types they map to. The sheet configuration describes the **presentation**: which columns appear, what data source to query, how to expand relationships for display, and how to format cells conditionally. diagram ## Why separate files? The separation enables several important patterns that would be impossible -- or at least impractical -- with a monolithic configuration. ### One data model, many sheet configurations A single data model -- for example, one defining `UserNeed`, `SystemRequirement`, `DesignRequirement`, `Hazard`, and `RiskControl` -- can power multiple sheet configurations. A requirements engineer might use a sheet that focuses on `UserNeed` to `SystemRequirement` traceability. A safety engineer might use a different sheet showing `Hazard` to `RiskControl` coverage. Both sheets reference the same data model, so entity types and relationships stay consistent. This is the most compelling reason for separation: **the data model is shared infrastructure, while sheet configurations are team-specific views**. ### Independent change cycles Data models change infrequently -- typically when a project adds a new entity type or relationship. Sheet configurations change regularly as teams adjust column visibility, add formatters, or create new views for different analysis perspectives. Keeping them separate means everyday column tweaks do not risk breaking the underlying data structure. ### Scope flexibility Both files can be scoped at the project level or the global level. A global data model can define a company-wide entity structure, while individual projects customize their sheet configurations to show only the columns relevant to their workflow. See [Global vs Project-Specific Configuration](/powersheet/concepts/global-vs-project-specific) for details on scope resolution. ## What the data model defines The data model YAML file has two primary sections: `domainModelTypes` and `relationships`. ### Entity types and Polarion mapping Each entity type maps to a Polarion work item type via the `polarionType` property: ```yaml theme={null} domainModelTypes: UserNeed: polarionType: user_need properties: description: severity: SystemRequirement: polarionType: sys_req properties: description: severity: DesignRequirement: polarionType: des_req properties: description: ``` The key on the left (`UserNeed`) is the **entity type name** used throughout Powersheet -- in sources, columns, and expansion paths. The `polarionType` value (`user_need`) is the Polarion work item type ID that this entity maps to. These are not interchangeable. A common error is using the Polarion type ID where the entity type name is expected, or vice versa. Always use the entity type name (e.g., `UserNeed`) in sheet configuration `sources` and `columns`. The Polarion type ID (e.g., `user_need`) belongs only in the `polarionType` field of the data model. Mixing them causes silent query failures. The `properties` section declares which fields are available for each entity type. These property names become the basis for column binding paths in the sheet configuration. ### Relationships Relationships connect entity types with direction, cardinality, storage mechanism, and navigation property names: ```yaml theme={null} 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 ``` Key properties: * **`from` / `to`** -- The source and target entity types. Must match keys in `domainModelTypes`. * **`cardinality`** -- How many instances can be linked: `many-to-one`, `one-to-many`, or `many-to-many`. * **`storage`** -- How the link is persisted in Polarion. `linkedWorkItems` is the only supported storage mechanism, using Polarion's native link mechanism. * **`linkRole`** -- The Polarion link role name (must exist in the project's link role configuration). * **`direct` / `back`** -- Navigation property names for forward and reverse traversal. The navigation property names (`direct.name` and `back.name`) are the bridge between the data model and the sheet configuration. They appear in the sheet configuration's `expand` clauses and column binding paths. For a deeper exploration of relationships and navigation, see [Entity Types and Relationships](/powersheet/concepts/entity-types-and-relationships) and [Navigation Properties](/powersheet/concepts/navigation-properties). ### Constraints The data model can also define constraints that control picker behavior when users create or link entities: ```yaml theme={null} domainModelTypes: SystemRequirement: polarionType: sys_req constraints: pick: document: moduleFolder: Requirements component: $context.source.document.component ``` Constraints like `pick.document.moduleFolder` filter which work items appear in picker dialogs. The `$context.source.document.component` syntax dynamically resolves to the current document's component, enforcing component-scoped relationships. See [Process Constraints](/powersheet/concepts/process-constraints) for the full constraint model. ## What the sheet configuration defines The sheet configuration YAML has several top-level sections: `sources`, `columns`, `views`, `formatters`, `styles`, `columnGroups`, and `sortBy`. ### Sources: what data to load Sources define how Powersheet queries the server API for data. Each source specifies the data model to use, an entity type to query, and navigation properties to expand: ```yaml theme={null} sources: - id: user_needs model: rtm query: from: UserNeed expand: - name: systemRequirements expand: - name: systemRequirement ``` The `model` value identifies which data model this source references -- this is the explicit connection point between the sheet configuration and the data model. The `query.from` value must match an entity type name from the referenced data model (not a Polarion type ID). The `expand` entries use navigation property names defined in the data model's `relationships` section. Sources can also define an `entityFactory` to set default property values when creating new entities: ```yaml theme={null} sources: - id: user_needs model: rtm query: from: UserNeed entityFactory: Status: Planned ``` Support experience shows that new users who jump straight to complex multi-level expansions encounter hard-to-diagnose errors. Start with a single source with no expansions, verify it works, then add `expand` entries one level at a time. ### Columns: how data appears Columns define the visual layout of the sheet. Each column key is a **binding path** -- a dot-separated path that traces through navigation properties to reach a data property: ```yaml theme={null} columns: title: title: Title hasFocus: true width: 300 chapter: title: Chapter display: title list: search: - title systemRequirements.systemRequirement.title: title: SysReq Title isReadOnly: true ``` The binding path determines what data appears in the column: * **`title`** -- A direct property on the root entity type * **`chapter`** -- A scalar navigation property (many-to-one); `display` specifies which property of the referenced entity to show * **`systemRequirements.systemRequirement.title`** -- A deep path through a many-to-many relationship (association entity `systemRequirements` to target entity `systemRequirement`, then its `title` property) ### Column properties at a glance | Property | Type | Default | Purpose | | ------------- | ----------------- | ------------ | ------------------------------------------------------- | | `title` | string | binding path | Display label for the column header | | `width` | number or string | `'*'` | Column width in pixels or relative (`'2*'`) | | `minWidth` | number | `150` | Minimum column width | | `visible` | boolean | `true` | Whether the column is shown by default | | `isReadOnly` | boolean | `false` | Prevents user editing | | `isRequired` | boolean | `false` | Validates before save | | `hasFocus` | boolean | `false` | Receives initial focus for new rows | | `hasUrl` | boolean | -- | Displays a link to the Polarion work item | | `multiItem` | boolean | `false` | Enables multi-item picker without creating a new level | | `formatter` | string | -- | References a conditional formatting rule | | `formula` | string | -- | JavaScript expression for calculated columns | | `render` | string | -- | Custom renderer or JavaScript expression | | `groupBy` | boolean or object | `false` | Groups rows by this column's values | | `frozen` | boolean | -- | Freezes the column for horizontal scrolling | | `aggregate` | string | -- | Aggregate function: `sum`, `avg`, `min`, `max`, `count` | | `columnGroup` | string | -- | Assigns column to a visual group | For the complete column property reference, see [Sheet Configuration Reference](/powersheet/reference/sheet-config/index). ### Views: named column presets Views let you define named column visibility presets without duplicating the entire sheet configuration: ```yaml theme={null} views: Without V&V: columns: validationTestCases.validationTestCase: visible: false systemRequirements.systemRequirement.verificationTestCases.verificationTestCase: visible: false ``` Each view extends the base column configuration by overriding specific properties (typically `visible`). One view can be marked as the default with `default: true`. If no default view is specified, the base configuration (called "Default view") is applied when the document loads. See [Views as Analysis Perspectives](/powersheet/concepts/views-as-perspectives) for the conceptual model behind views. ### Formatters, styles, and column groups The sheet configuration also controls visual presentation through: * **`formatters`** -- Conditional formatting rules that evaluate a JavaScript expression against each row and apply a style when the condition is true * **`styles`** -- Named style definitions with CSS-like properties (`color`, `backgroundColor`, `textDecoration`) * **`columnGroups`** -- Visual groupings with shared header styling and optional collapse behavior via `collapseTo` * **`sortBy`** -- Default client-side sort order specifying `columnId` and `direction` ## How they connect at runtime When a Powersheet document loads, the following sequence occurs: 1. **Configuration resolution** -- The server loads the sheet configuration YAML associated with the document (determined by the document's sheet config custom field) 2. **Data model loading** -- The server API loads the data model referenced by each source's `model` field, building the metadata that describes entity types, properties, and relationships 3. **Source queries** -- For each source, the client query framework issues queries using `query.from` to identify the root entity type, then expands navigation properties as specified in `expand` 4. **Column binding** -- Each column's binding path is resolved against the metadata. The path is walked through navigation properties until the target data property is reached 5. **Rendering** -- The sheet renders with the resolved data, applying formatters, styles, views, and column groups diagram The critical connection point is the **navigation property name**. When a sheet configuration declares `expand: [{ name: systemRequirements }]`, the metadata system looks up `systemRequirements` in the data model's relationship definitions to determine the target entity type, cardinality, and link role. When a column binding path starts with `systemRequirements.systemRequirement.title`, the same metadata resolves each segment of the path. ## How cardinality affects the connection The cardinality defined in the data model relationship determines how the sheet configuration must reference it. This is where the two files' concerns meet most concretely: | Cardinality | Data Model | Source Expand | Column Binding | UI Behavior | | ---------------------- | ------------------------------- | ------------------------------------------------------------- | -------------------------------------- | ----------------------------- | | **N:1** (many-to-one) | `direct.name: chapter` | `- name: chapter` | `chapter`, `chapter.title` | Single-value reference picker | | **1:N** (one-to-many) | `back.name: userNeeds` | `- name: userNeeds` | `userNeeds` (new level) | Child rows (new sheet level) | | **M:N** (many-to-many) | `back.name: systemRequirements` | `- name: systemRequirements` then `- name: systemRequirement` | `systemRequirements.systemRequirement` | Multi-item reference picker | For many-to-many relationships, the expand pattern requires two levels -- first the association collection, then the target entity -- and the column binding path mirrors this two-segment structure. For many-to-one relationships, a single navigation property name suffices. See [Link Cardinality](/powersheet/concepts/link-cardinality) for a deeper exploration of how cardinality affects sheet behavior. ## Common misconceptions ### "I can define columns for any Polarion field" Columns can only reference properties and navigation properties that exist in the data model. If a Polarion custom field is not declared in the entity type's `properties` section, it will not be available for column binding. The data model acts as a filter -- it determines the boundary of what data is accessible. ### "Entity type names and Polarion type IDs are the same thing" They are distinct. The entity type name (`SystemRequirement`) is chosen by the administrator and can be anything meaningful. The Polarion type ID (`sys_req`) must match an existing work item type in Polarion. They connect through the `polarionType` field. In sources and columns, always use the entity type name. ### "I need a separate data model for each sheet configuration" Multiple sheet configurations can (and typically do) share the same data model. The data model defines the full data landscape; each sheet configuration selects a subset to display. This is by design -- it keeps the entity type and relationship definitions consistent across all views. ### "Changing a column definition will affect my data" Sheet configuration changes are purely presentational. Changing a column's `title`, `width`, `visible`, or `formatter` does not alter any data in Polarion. The data model and Polarion's link roles are the only configurations that affect data structure. This is why it is safe to experiment with sheet configurations without risk to your data. ## Practical guidelines **When to modify the data model:** * Adding a new entity type to your data landscape * Defining a new relationship between existing entity types * Adding a new property that needs to be queryable or editable * Changing picker constraints for entity creation **When to modify the sheet configuration:** * Adding or removing visible columns * Changing column widths, titles, or sort order * Creating new views for different stakeholders * Adding conditional formatting rules * Adjusting source queries or expansion depth **When to modify both:** * Introducing a completely new entity type that needs to appear in the sheet -- define it in the data model first, then add sources and columns in the sheet configuration Start with the simplest possible configuration: one source with a single entity type, a few columns showing basic properties, no expansions. Verify it loads correctly. Then add one expansion at a time, checking at each step. This approach makes it easy to identify which change caused an error if something goes wrong. ## Further reading * [Entity Types and Relationships](/powersheet/concepts/entity-types-and-relationships) -- Deep dive into data model entity definitions * [Navigation Properties](/powersheet/concepts/navigation-properties) -- How navigation property names work across both files * [Hierarchy and Traceability](/powersheet/concepts/hierarchy-and-traceability) -- How expansion paths create hierarchical views * [YAML Configuration System](/powersheet/concepts/yaml-configuration) -- YAML syntax and structure conventions * [Model-Driven Design](/powersheet/concepts/model-driven-design) -- The philosophy behind separating data structure from presentation * [Source Configuration](/powersheet/concepts/source-configuration) -- Detailed guide to configuring data sources ***