Skip to main content
In Powersheet, the YAML file defining entity types and relationships is called the domain model (not “data model”). “Entity type” refers to domain model concepts; “work item type” refers to the underlying Polarion type.

​
Domain Model Basics

​
What is a domain model and why do I need one?

The domain model is a YAML configuration file that defines the semantic layer between Polarion’s native work item types and Powersheet’s sheet views. It maps Polarion types, link roles, and custom fields into structured entity types and relationships that Powersheet uses for querying, displaying, and editing data. Without a domain model, Powersheet cannot understand which work items to load or how they relate to each other. See Creating Your First Data Model for a step-by-step tutorial.

​
Where do I manage domain models?

Domain models are managed through the Polarion administration interface at Administration > Nextedy POWERSHEET > Domain Models. You can create both global models (available to all projects) and project-specific models. Multiple models can coexist, and each sheet configuration references a specific model by name.

​
What is the Model Helper tool?

Model Helper is a configured widget that dynamically visualizes the domain model structure and the proper bindings between entities. It is set up as a LiveReport page and requires four parameters: model (the model name), projectId, startEntity (the root entity for expansion), and depth (how many levels deep to explore). This tool is especially useful for understanding expansion paths when configuring data sources.

​
Entity Types and Relationships

​
How do I define entity types in the domain model?

Entity types are defined in the domainModelTypes section of the YAML file. Each entity type maps to one or more Polarion work item types via the polarionType property, which accepts either a single string or an array of strings. Entity types also define their own properties array for specifying which fields are exposed in the sheet. 
domainModelTypes:
  UserNeed:
    polarionType: user_need
    properties:
      - name: title
      - name: status
      - name: severity
  SystemRequirement:
    polarionType:
      - sys_req
      - des_req
    properties:
      - name: title
      - name: priority

​
What relationship cardinalities are supported?

Powersheet supports two relationship cardinality types in the domain model:
CardinalityDescriptionExample
many-to-oneMultiple entities link to a single targetMany SystemRequirement items link to one UserNeed
many-to-manyEntities link freely in both directionsTestCase items linked to multiple SystemRequirement items
Relationships are defined in the relationships array of the domain model and map to Polarion link roles. They enable expansion paths for navigating between related entity types in the sheet.

​
How do entity type properties work?

Each property in the domain model defines a field exposed in the Powersheet sheet. Key property attributes include:
AttributePurposeDefault
nameClient-facing property nameRequired
serverNamePolarion field name overrideSame as name
customFieldNamePolarion custom field ID—
readableCan be read by userstrue
updatableCan be modified by userstrue
scalarSingle value vs. collectiontrue
enumValuesValid enum option IDs—
Use serverName to alias Polarion field names to more user-friendly names, and customFieldName when a property maps to a Polarion custom field rather than a built-in field.

​
Configuration Tips

​
Should I start with a complex or simple domain model?

Always start with the simplest possible configuration and extend incrementally. Begin with a single entity type and one or two properties, verify it works in a sheet, then add relationships and additional entity types one at a time. Jumping directly to a complex multi-entity model leads to hard-to-diagnose configuration errors.
See Incremental Configuration Approach for guidance on building up your configuration step by step.

​
Can domain model types be defined as a map or an array?

The domainModelTypes section supports both formats. You can define types as a map keyed by type name (recommended for readability) or as an array of type objects. When using the map format, the type name is automatically set from the map key. Both formats produce the same result, so choose whichever fits your workflow better.

​
How does Powersheet validate my domain model configuration?

Powersheet generates a JSON Schema from your domain model definition that validates entity types, relationships, properties, and Polarion prototype references. The configuration editor uses this schema to provide real-time feedback, ensuring that polarionType values reference valid Polarion prototypes and that required fields are present. See Configuration FAQ for more on the editor’s validation capabilities.
KB ArticlesSupport TicketsSource Code
  • DatabridgeConstants.java
  • prod-powersheet-src/com.nextedy.powersheet/src/META-INF/hivemodule.xml
  • build.properties
  • prod-powersheet-src/com.nextedy.powersheet.client/cypress/fixtures/configurations/constraints_composing.template.yaml
  • DomainModelV2.java