See also: Domain Model Types | Properties | Relationships | Cardinality
Constraint Stages Overview
Powersheet supports three constraint stages, each applied at a different point in the entity lifecycle:
| Stage | Purpose | When Applied |
|---|
load | Filters which entities are loaded and displayed in the sheet | At query/load time |
pick | Filters which entities appear in selection dropdowns (pickers) | When opening a picker dialog |
create | Specifies default values for newly created entities | At entity creation time |
Stage Cascading
Constraint stages cascade upward — more specific stages inherit all constraints from less specific ones, combined with AND logic:
- Load stage: applies only
load constraints
- Pick stage: applies
load + pick constraints (AND)
- Create stage: applies
load + pick + create constraints (AND)
If no create constraints are defined, the system automatically uses pick constraints for the create stage. This means defining pick constraints also affects item creation unless explicit create constraints override them.
Because load constraints propagate to all subsequent stages, a load constraint that restricts entities to a specific document will also restrict picker results and creation scope. You only need to define more specific constraints when pick or create require additional filtering beyond what load already provides.
Constraint Properties Reference
Top-Level Structure
| Name | Type | Default | Description |
|---|
constraints | object | None | Top-level constraint container for an entity type. Contains load, create, and/or pick sub-objects. Defined within a domainModelTypes entry. |
constraints.load | object | None | Query constraint defining which entities to load from Polarion. Filters entities based on document properties, work item fields, or other criteria. |
constraints.pick | object | None | Picker constraint filtering which entities appear in selection dropdowns when creating or editing relationships. Inherits load constraints via cascading. |
constraints.create | object | None | Creation constraint specifying initial values or scope for newly created entities. Inherits both load and pick constraints via cascading. |
Document Constraint Properties
Each constraint stage accepts a document object for document-based filtering. These properties scope entities to specific Polarion LiveDoc documents.
| Name | Type | Default | Description |
|---|
document | object | None | Document-based constraint object. Scopes entities to work items within specific LiveDoc documents. |
document.id | string | None | Polarion document ID to constrain entities to. Matches the document’s internal identifier (e.g., "Requirements"). Supports comparison operators. |
document.title | string | None | Polarion document title to constrain entities to. Matches the document’s display title. Supports comparison operators. |
Only document.id and document.title are supported as constrainable document properties. Other document metadata fields cannot be used in constraint expressions.
Field-Level Constraint Properties
In addition to document constraints, each stage can constrain on work item field values:
| Name | Type | Default | Description |
|---|
<fieldName> | string or object | None | Constrains the named work item field to a specific value or comparison expression. The field name must match a property defined on the entity type or a built-in Polarion field. |
Comparison Operators
Constraint values support five comparison operators for flexible matching:
| Operator | Syntax | Description | Example |
|---|
equals | value or { equals: value } | Exact match (default when a plain string is provided) | severity: high |
contains | { contains: value } | Substring match — true if the field value contains the specified text | title: { contains: "safety" } |
in | { in: [v1, v2, ...] } | Set membership — true if the field value matches any item in the list | status: { in: [approved, reviewed] } |
startsWith | { startsWith: value } | Prefix match — true if the field value starts with the specified text | id: { startsWith: "REQ-" } |
endsWith | { endsWith: value } | Suffix match — true if the field value ends with the specified text | title: { endsWith: "-draft" } |
When a constraint value is a plain string (not an object), it is treated as an equals comparison. Use the object syntax only when you need a different operator.
Logical Operators
AND Logic (Between Constraints)
Multiple constraints within the same stage are combined with AND logic. All conditions must be true for an entity to pass the constraint:
domainModelTypes:
SystemRequirement:
polarionType: sys_req
constraints:
load:
severity: high
status: approved
# Result: severity = "high" AND status = "approved"
OR Logic (Within Document Block)
Inside the document block, OR logic is supported. An entity passes the constraint if it matches any of the document conditions:
domainModelTypes:
SystemRequirement:
polarionType: sys_req
constraints:
load:
document:
id:
in: [Requirements, SafetyRequirements]
# Result: document.id = "Requirements" OR document.id = "SafetyRequirements"
Field-level constraints use AND logic between each other, while the in operator provides OR semantics within a single field. This combination covers most practical filtering scenarios.
Dynamic Context Constraints
Constraints can reference the current runtime context using special context expressions. This enables constraints that are resolved dynamically based on the active sheet session.
| Context Variable | Description |
|---|
$currentDocument.id | ID of the document currently open in the Polarion LiveDoc |
$currentDocument.title | Title of the currently open document |
domainModelTypes:
UserNeed:
polarionType: user_need
constraints:
load:
document:
id: $currentDocument.id
pick:
document:
id: $currentDocument.id
The full list of available context variables may extend beyond $currentDocument. Consult the application release notes for the latest supported context expressions.
Constraint Composition
Constraints can be defined at multiple stages simultaneously on the same entity type. When combined, stages cascade as described above.
Composition Example
domainModelTypes:
DesignRequirement:
polarionType: des_req
constraints:
load:
document:
id: $currentDocument.id
pick:
status:
in: [approved, reviewed]
create:
severity: medium
| Stage | Effective Constraints |
|---|
| Load | document.id = $currentDocument.id |
| Pick | document.id = $currentDocument.id AND status IN [approved, reviewed] |
| Create | document.id = $currentDocument.id AND status IN [approved, reviewed] AND severity = medium |
Constraint composition can produce empty results if constraints conflict. For example, a load constraint limiting entities to status: approved combined with a pick constraint for status: draft would produce no picker results because both conditions apply simultaneously (AND logic). Review your cascading chain to avoid contradictions.
Complete YAML Examples
Load-Only Constraint
Restrict an entity type to only show work items from a specific document:
domainModelTypes:
UserNeed:
polarionType: user_need
properties:
description:
severity:
constraints:
load:
document:
id: Requirements
UserNeed items in the “Requirements” document are loaded into the sheet. Pickers and creation inherit this constraint.
Pick-Only Constraint
Allow all entities to load but restrict picker options:
domainModelTypes:
SystemRequirement:
polarionType: sys_req
properties:
description:
severity:
constraints:
pick:
status:
in: [approved, reviewed]
SystemRequirement items load normally. Picker dialogs only show items with status approved or reviewed. Since no create constraints are defined, the pick constraints apply as a fallback during creation as well.
Create-Only Constraint
Set default values when creating new entities without affecting loading or picking:
domainModelTypes:
Hazard:
polarionType: hazard
properties:
severity:
status:
constraints:
create:
severity: low
status: draft
severity: low and status: draft.
Current-Document Scoping
Dynamically scope all stages to the currently open document:
domainModelTypes:
UserNeed:
polarionType: user_need
properties:
description:
severity:
constraints:
load:
document:
id: $currentDocument.id
pick:
document:
id: $currentDocument.id
create:
document:
id: $currentDocument.id
Multi-Stage Composition
A complete example combining all three stages with different scoping:
domainModelTypes:
Chapter:
polarionType: heading
UserNeed:
polarionType: user_need
properties:
description:
severity:
constraints:
load:
document:
id: $currentDocument.id
pick:
status:
in: [approved, reviewed, draft]
create:
severity: medium
SystemRequirement:
polarionType: sys_req
properties:
description:
severity:
constraints:
load:
document:
id: $currentDocument.id
pick:
severity:
in: [high, critical]
relationships:
- from: SystemRequirement
to: UserNeed
cardinality: many-to-many
storage: linkedWorkItems
linkRole: decomposes
direct:
name: userNeeds
back:
name: systemRequirements
UserNeed items load from the current document, pickers show only approved/reviewed/draft items from that document, and new items default to severity: mediumSystemRequirement items load from the current document, pickers show only high/critical severity items from that document- The
relationships section connects the two entity types — picker constraints on UserNeed affect which items appear when linking a SystemRequirement to user needs
Constraints and Relationships
Constraints interact with Relationships through picker behavior. When a sheet column binds to a navigation property (e.g., userNeeds or chapter), the picker dialog for that column uses the pick constraints defined on the target entity type.
| Relationship | Column Binding | Picker Constrained By |
|---|
SystemRequirement -> UserNeed | userNeeds | UserNeed.constraints.pick |
UserNeed -> Chapter | chapter | Chapter.constraints.pick |
If a picker shows too many or too few items when linking entities, check the pick constraints on the target entity type. Remember that load constraints cascade into pick, so an overly restrictive load constraint will also limit picker results.
Sheet-Level Constraints
In addition to domain model constraints, constraints can also be applied at the sheet configuration level through source queries. Source-level constraints use the query and expand syntax rather than the constraints YAML key.
sources:
- id: user_needs
query:
from: UserNeed
expand:
- name: chapter
- Domain model constraints (this page) define permanent scoping rules for an entity type across all sheets
- Source query constraints restrict which entities appear in a specific sheet configuration
For source query syntax, see Sources. For query filtering options, see EntityQuery and Document Filtering.
Quick Reference
Constraint Stage Summary
| Stage | Inherits From | Purpose | Fallback |
|---|
load | — | Filter entities at query time | None |
pick | load | Filter picker dropdown items | None |
create | load + pick | Set defaults on new entities | Falls back to pick if undefined |
Operator Summary
| Operator | Syntax | Logic |
|---|
equals | field: value | Exact match |
contains | field: { contains: value } | Substring |
in | field: { in: [a, b] } | Any match (OR) |
startsWith | field: { startsWith: value } | Prefix |
endsWith | field: { endsWith: value } | Suffix |
Cascading Rules
| Rule | Behavior |
|---|
| Multiple fields in one stage | AND logic |
in operator values | OR logic (within single field) |
| Cross-stage inheritance | AND with parent stage constraints |
Missing create stage | Falls back to pick constraints |
| Conflicting constraints | May produce empty result set |
Sources: DomainModelTypeV2.java, Relationship.java, DomainModelV2.java, rtm_model.yaml, riskmanagement_model.yaml, Constraints in Powersheet, Model / Source / Columns: Cardinality Reference 
