Data Model vs Sheet Configuration - Nextedy Documentation

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

	Domain 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 > Domain Models	Administration > Nextedy POWERSHEET > Sheet Configurations
Scope	Project or Global	Project or Global

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

Why separate files?

The separation enables several important patterns that would be impossible — or at least impractical — with a monolithic configuration.

One domain model, many sheet configurations

A single domain 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 domain model, so entity types and relationships stay consistent. This is the most compelling reason for separation: the domain model is shared infrastructure, while sheet configurations are team-specific views.

Independent change cycles

Domain 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 domain 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 for details on scope resolution.

What the domain model defines

The domain 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:

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

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 domain 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 and Navigation Properties.

Constraints

The domain model can also define constraints that control picker behavior when users create or link entities:

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 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 an entity type to query and navigation properties to expand:

sources:
  - id: user_needs
    query:
      from: UserNeed
    expand:
      - name: systemRequirements
        expand:
          - name: systemRequirement

The query.from value must match an entity type name from the domain model (not a Polarion type ID). The expand entries use navigation property names defined in the domain model’s relationships section. Sources can also define an entityFactory to set default property values when creating new entities:

sources:
  - id: user_needs
    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:

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.

Views: named column presets

Views let you define named column visibility presets without duplicating the entire sheet configuration:

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

Configuration resolution — The server loads the sheet configuration YAML associated with the document (determined by the document’s sheet config custom field)
Domain model loading — The server API loads the domain model referenced by the configuration, building the metadata that describes entity types, properties, and relationships
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
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
Rendering — The sheet renders with the resolved data, applying formatters, styles, views, and column groups

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 domain 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 domain model relationship determines how the sheet configuration must reference it. This is where the two files’ concerns meet most concretely:

Cardinality	Domain 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 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 domain 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 domain 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 domain model for each sheet configuration”

Multiple sheet configurations can (and typically do) share the same domain model. The domain 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 domain 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 domain 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 domain 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.

​Two files, two concerns

​Why separate files?

​One domain model, many sheet configurations

​Independent change cycles

​Scope flexibility

​What the domain model defines

​Entity types and Polarion mapping

​Relationships

​Constraints

​What the sheet configuration defines

​Sources: what data to load

​Columns: how data appears

​Column properties at a glance

​Views: named column presets

​Formatters, styles, and column groups

​How they connect at runtime

​How cardinality affects the connection

​Common misconceptions

​”I can define columns for any Polarion field”

​”Entity type names and Polarion type IDs are the same thing”

​”I need a separate domain model for each sheet configuration”

​”Changing a column definition will affect my data”

​Practical guidelines

​Further reading

Two files, two concerns

Why separate files?

One domain model, many sheet configurations

Independent change cycles

Scope flexibility

What the domain model defines

Entity types and Polarion mapping

Relationships

Constraints

What the sheet configuration defines

Sources: what data to load

Columns: how data appears

Column properties at a glance

Views: named column presets

Formatters, styles, and column groups

How they connect at runtime

How cardinality affects the connection

Common misconceptions

”I can define columns for any Polarion field”

”Entity type names and Polarion type IDs are the same thing”

”I need a separate domain model for each sheet configuration”

”Changing a column definition will affect my data”

Practical guidelines

Further reading