Skip to main content

​
The design principle

In a model-driven system, configuration files describe what should happen, not how it should happen. The domain model declares entity types, their properties, and their relationships. The Powersheet runtime reads this declaration and automatically generates the metadata, queries, pickers, and validation rules needed to render and edit the data. This is the opposite of a code-driven approach where each new entity type or relationship would require custom development. With Powersheet, adding a new entity type is a YAML change, not a code change. Think of it like a building blueprint. The blueprint (domain model) specifies which rooms exist, how they connect, and what each room contains. The construction crew (Powersheet runtime) reads the blueprint and builds everything accordingly. If you want to add a new room, you update the blueprint rather than writing new construction instructions from scratch. diagram

​
The three configuration layers

Powersheet’s model-driven architecture rests on three distinct configuration layers that work together. Understanding how they connect is essential for building effective sheets.
LayerFilePurpose
Domain modelmodel.yamlDefines entity types, properties, and relationships
Sheet configurationpowersheet.yamlDefines columns, views, formatters, and sources
Polarion projectLink roles, work item typesProvides the underlying data infrastructure
The domain model sits between Polarion and the sheet configuration. It maps Polarion’s native concepts (work item types, link roles, custom fields) into a consistent vocabulary of entity types and navigation properties. The sheet configuration then references that vocabulary without needing to know the Polarion-level details. diagram The navigation property names are the thread that connects these layers. A relationship defined in the domain model creates a named navigation property. The sheet sources use that same name to expand into related data. The sheet columns use it to bind and display values. If any layer uses a different name, the connection breaks.

​
From YAML to metadata

When a powersheet document is opened, the domain model YAML is processed through a metadata generation pipeline. Each domainModelTypes entry becomes an entity type with:
  • A primary key property (objectId)
  • A polarionType property linking to the Polarion work item type
  • Built-in properties: title, icon, and automatically added document and project navigation properties
  • Custom properties from the properties section, each mapped to Polarion work item fields
Here is a minimal domain model showing how entity types are declared: 
domainModelTypes:
  UserNeed:
    polarionType: user_need
    properties:
      description:
      severity:

  SystemRequirement:
    polarionType: sys_req
    properties:
      description:
      severity:
Each key under domainModelTypes (like UserNeed) becomes the entity type name used throughout the rest of the configuration. The polarionType maps it to the corresponding Polarion work item type. Properties listed under properties become available as columns in the sheet.

​
Relationships and navigation properties

Relationships define how entity types connect to each other. Each relationship specifies:
  • from / to — the source and target entity types
  • cardinality — the multiplicity (many-to-one, one-to-many, many-to-many)
  • storage — how the link is persisted in Polarion (linkedWorkItems is the only supported storage mechanism)
  • linkRole — the Polarion link role that implements the connection
  • direct / back — the navigation property names for forward and reverse traversal
relationships:
  - from: SystemRequirement
    to: UserNeed
    cardinality: many-to-many
    storage: linkedWorkItems
    linkRole: decomposes
    direct:
      name: userNeeds
    back:
      name: systemRequirements
In this example, the relationship creates two navigation properties:
  • direct.name: userNeeds — navigate from a SystemRequirement to its linked UserNeed items
  • back.name: systemRequirements — navigate from a UserNeed to its linked SystemRequirement items
The direct and back object notation is the current relationship syntax. Each contains a name field specifying the navigation property. This syntax replaced an earlier flat format and is the only supported approach.

​
Built-in entity types

Two built-in entity types are always available regardless of the domain model configuration:
Entity typePurpose
DocumentRepresents Polarion modules (LiveDocs). Exposes properties like moduleName, moduleFolder, title, and allowedWITypes
ProjectRepresents Polarion projects. Automatically linked to all work item entity types
These built-in types enable features like document-scoped filtering in picker constraints and project-level navigation without any explicit configuration.

​
The mapping layer

A key advantage of model-driven design is that the domain model acts as a mapping layer between Polarion’s native data structures and the Powersheet view. This is significant because:
  • Different projects can have different Polarion type names for the same conceptual entity. The domain model normalizes these: one project’s sys_requirement and another’s systemReq can both map to a SystemRequirement entity type in the domain model.
  • Link roles vary between projects. The domain model abstracts them behind navigation property names, so the sheet configuration remains identical.
  • A single sheet configuration can be reused across projects that share the same domain model structure but differ in Polarion-level details.
This mapping layer is why the domain model and sheet configuration are separate files. The domain model handles project-specific Polarion mappings. The sheet configuration handles presentation and interaction. You can pair one domain model with multiple sheet configurations, or update the Polarion mappings without touching the column layout.

​
How cardinality shapes the sheet

The cardinality of a relationship determines how data flows through sources, how columns bind to properties, and what users see in the sheet. This is perhaps the most important concept for understanding how model-driven design translates into a working UI.
CardinalityModel definitionSource expandColumn bindingUI behavior
N:1cardinality: many-to-one, direct.name: chapter- name: chapterchapter, chapter.titleSingle-value reference picker
1:NReverse of N:1, back.name: userNeeds- name: userNeedsuserNeedsChild rows (new hierarchy level)
M:Ncardinality: many-to-many, back.name: systemRequirements- name: systemRequirements then - name: systemRequirementsystemRequirements.systemRequirementMulti-item reference picker

​
Many-to-one: scalar references

When an entity has a many-to-one relationship (each UserNeed belongs to exactly one Chapter), the navigation property is scalar. The source expands it with a single name, and columns can either display a picker for the reference or read through to display properties of the referenced entity: 
columns:
  chapter:
    title: Chapter
    display: title
    list:
      search:
        - title
  chapter.title:
    title: Chapter Title
    isReadOnly: true

​
One-to-many: hierarchical expansion

The reverse side of a many-to-one relationship is one-to-many. This is where Powersheet’s hierarchical nature becomes visible. When a Chapter expands into its userNeeds, each child UserNeed appears as a nested row under the parent. The expand creates a new level in the sheet hierarchy.

​
Many-to-many: association entities

Many-to-many relationships use an association entity between the two types. The source expand goes through two levels — first the association collection, then the target entity. The column binding uses dot-notation to reach through: 
sources:
  - id: user_needs
    query:
      from: UserNeed
    expand:
      - name: systemRequirements
        expand:
          - name: systemRequirement

columns:
  systemRequirements.systemRequirement:
    title: System Requirement
    list:
      search:
        - objectId
        - title
      createNew: true
The two-level expand (systemRequirements then systemRequirement) and the dot-notation column key (systemRequirements.systemRequirement) are the telltale signs of a many-to-many relationship. When a sheet has two different work item types linked to the same parent entity, the second linked column must declare multiItem: true in the sheet configuration.
A dot-separated column key like systemRequirements.systemRequirement.title reads as: “Starting from the current entity, follow the systemRequirements navigation property (association collection), then follow systemRequirement (target entity), then display the title property.” Each segment maps to a relationship or property defined in the domain model.

​
Constraints and picker filtering

The domain model also drives picker constraints — rules that filter which items appear when a user selects a related entity. Constraints can restrict picker results by:
  • Document location (moduleFolder, moduleName) — limit selections to items in specific spaces
  • Document type (type) — only show items from documents of a certain type
  • Component (component) — scope selections to the same component as the source entity using $context.source.document.component
domainModelTypes:
  SystemRequirement:
    polarionType: sys_req
    constraints:
      pick:
        document:
          moduleFolder: Requirements
          type: requirements_specification
This constraint means that when a user picks a SystemRequirement in the sheet, the picker only shows items from documents in the Requirements space that have the requirements_specification document type. The runtime applies these filters automatically based on the model declaration.
Dynamic context references like $context.source.document.component resolve at runtime based on the current entity’s document context. The exact behavior depends on the project’s component configuration in Polarion.

​
Why model-driven design matters

The model-driven approach delivers several practical benefits that become increasingly valuable as configurations grow in complexity: Consistency across the organization. Because the domain model is a single YAML file shared across sheet configurations, all sheets that reference the same model use identical entity definitions, relationship rules, and navigation properties. Changes propagate automatically. Separation of concerns. Polarion administrators manage work item types and link roles. Domain model authors map those to a clean entity vocabulary. Sheet designers compose columns and views without worrying about Polarion internals. Each role works at the appropriate level of abstraction. Reduced configuration errors. New users frequently encounter issues when jumping straight to complex multi-entity configurations. The model-driven pattern encourages an incremental approach: define one entity type, verify it works, then add relationships one at a time. Each addition is a self-contained YAML block that can be validated independently. Reusability across projects. A well-designed domain model can serve multiple Polarion projects by updating only the polarionType and linkRole mappings. The sheet configurations, sources, and column bindings remain unchanged because they reference entity type names and navigation properties, not Polarion-specific identifiers. For a detailed comparison of the domain model and sheet configuration files, see Data Model vs Sheet Configuration. To understand how entity types and relationships are structured in practice, see Entity Types and Relationships. For hands-on configuration guidance, see the Data Model Guides.
Source Code: DomainModelV2.java, Relationship.java, Direction.java, whole_rtm.template.yamlTickets: Configuration setup guidance, domain model configuration support, multi-item column setup