Skip to main content
See also: Domain Model Types | Properties | Relationships

​
Constraint Types Overview

diagram Powersheet supports three constraint types:
Constraint TypePurposeWhen Applied
loadFilters which entities are loaded and displayed in the sheetAt query/load time
createSpecifies default values for newly created entitiesAt entity creation time
pickFilters which entities appear in selection dropdownsWhen opening a picker dialog

​
Stage Cascading

Constraint stages cascade upward — more specific stages inherit 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.

​
Constraint Properties

All three constraint types share the same document sub-properties for document-based filtering:
NameTypeDefaultDescription
constraintsobjectNoneTop-level constraint container for an entity type. Contains load, create, and/or pick sub-objects.
loadobjectNoneQuery constraint defining which entities to load. Filters entities based on document properties or other criteria.
createobjectNoneDefault value constraint specifying initial values for newly created entities.
pickobjectNonePicker constraint filtering which entities appear in selection dropdowns when creating relationships.

​
Document Constraint Properties

Each constraint type accepts a document object with the following properties:
NameTypeDefaultDescription
documentobjectNoneDocument-based constraint object specifying document properties for filtering or defaults.
document.moduleFolderstringNonePolarion module folder (space) path for document location constraints.
document.moduleNamestringNonePolarion module (document) name for exact name matching.
document.typestringNonePolarion document type for constraints. Filters documents by their type classification.
document.idstringNonePolarion document ID in folder/name format (e.g., Requirements/UserNeedSpecification).
document.titlestringNonePolarion document title for filtering by display name.
document.componentstringNonePolarion component for constraints. Supports $context references for dynamic scoping.

​
Load Constraints

Load constraints filter which entities are visible when loading data into the sheet. They apply query-time filtering based on document properties. 
domainModelTypes:
  UserNeed:
    polarionType: userNeed
    constraints:
      load:
        document:
          type: specification
    properties:
      title:
      description:
Load constraints operate at the domain model level and affect all queries for this entity type. For per-source query filtering, use the where clause in the Sources configuration.

​
Create Constraints

Create constraints restrict where new work items of a specific type can be created, specifying the target document for new entities. 
domainModelTypes:
  SystemRequirement:
    polarionType: systemRequirement
    constraints:
      create:
        document:
          moduleFolder: Requirements
          moduleName: System Requirements
          type: systemSpecification
    properties:
      title:
      description:
      severity:
When a user creates a new SystemRequirement, it will automatically be placed in the document at Requirements/System Requirements with the systemSpecification document type.

​
Pick Constraints

Pick constraints filter which entities are available in relationship picker dialogs. They scope the options users see when selecting linked items. 
domainModelTypes:
  DesignRequirement:
    polarionType: designOutput
    constraints:
      pick:
        document:
          moduleFolder: Design
          type: designSpecification
    properties:
      title:
      description:
Pick constraints only affect picker dialogs — they do not filter entities already loaded in the sheet. Use load constraints to filter the main entity list.

​
Comparison Operators

Document constraint properties support five comparison operators. The default is strict equality when a plain value is provided.
OperatorSyntaxDescription
(equals)type: srsExact match (default when a plain value is given)
containsmoduleName: { contains: Spec }Value contains the specified text
intype: { in: [srs, drs] }Value matches any item in the list
startsWithtitle: { startsWith: REQ- }Value starts with the specified prefix
endsWithtitle: { endsWith: -Draft }Value ends with the specified suffix
constraints:
  load:
    document:
      type:
        in: [systemRequirementsSpecification, designRequirementsSpecification]
      moduleName:
        contains: Specification

​
Logical Operators

Multiple properties at the same level are implicitly combined with AND: 
constraints:
  load:
    document:
      moduleName:
        contains: Spec
      moduleFolder: Requirements    # AND -- both conditions must match
Use or inside the document block for OR logic: 
constraints:
  load:
    document:
      or:
        - moduleName: Alpha
        - moduleName: Beta
The document key must always be at the top level of the constraint. Place or blocks inside document, not around it. Wrapping document inside an or block is invalid.

​
Dynamic Context References

Constraints can use $context references for dynamic scoping based on the source entity’s properties: 
domainModelTypes:
  SystemRequirement:
    polarionType: systemRequirement
    constraints:
      pick:
        document:
          component: $context.source.document.component
    properties:
      title:
      description:
Context ReferenceDescription
$context.source.documentReference to the source entity’s document properties.
$context.source.document.componentDynamically resolves to the component property of the source entity’s document.
Constraints can also be applied to individual navigation properties within relationships, enabling context-aware filtering on specific expansion paths: 
relationships:
  - from: UserNeed
    to: SystemRequirement
    cardinality: one-to-many
    storage: linkedWorkItems
    linkRole: refines
    direct:
      name: systemRequirements
    back:
      name: userNeeds
      constraints:
        load:
          document:
            component: $context.source.document.component
This configuration filters the userNeeds back-navigation to only include items from documents with the same component as the source entity’s document.

​
Source-Level Constraints

The sheet configuration sources section supports applyCurrentDocumentTo, which constrains a specific entity type to the current document context: 
sources:
  - id: requirements
    title: Requirements
    model: rtm
    query:
      from: UserNeed
    constraints:
      applyCurrentDocumentTo: SystemRequirement
    expand:
      - name: systemRequirements
        title: System Requirements

​
Constraint Composition

When constraints are defined at multiple levels (entity type + relationship, or combined with sheet-level applyCurrentDocumentTo), they are combined using AND logic. All constraints must be satisfied simultaneously.
If entity-level and relationship-level constraints specify incompatible values for the same property, the AND composition results in no matching items. Powersheet does not warn about conflicting constraints — an empty result set is the only indicator.

​
Initial Values from Constraints

When creating a new work item, Powersheet uses constraint values as initial defaults. For example, if a load constraint specifies document.type: systemRequirementsSpecification, new items are automatically assigned to a document of that type.

​
Complete YAML Example

domainModelTypes:
  Document:
    properties:
      title:
      type:

  Chapter:

  UserNeed:
    polarionType: userNeed
    constraints:
      load:
        document:
          type: specification
      create:
        document:
          moduleFolder: Requirements
          moduleName: User Needs
          type: specification
      pick:
        document:
          moduleFolder: Requirements
    properties:
      title:
      description:
      severity:
      component:

  SystemRequirement:
    polarionType: systemRequirement
    constraints:
      create:
        document:
          moduleFolder: Requirements
          moduleName: System Requirements
          type: systemSpecification
      pick:
        document:
          component: $context.source.document.component
    properties:
      title:
      description:
      severity:

  DesignRequirement:
    polarionType: designOutput
    constraints:
      pick:
        document:
          moduleFolder: Design
          type: designSpecification
    properties:
      title:
      description:

relationships:
  - from: UserNeed
    to: SystemRequirement
    cardinality: one-to-many
    storage: linkedWorkItems
    linkRole: refines
    direct:
      name: systemRequirements
    back:
      name: userNeeds

  - from: SystemRequirement
    to: DesignRequirement
    cardinality: one-to-many
    storage: linkedWorkItems
    linkRole: refines
    direct:
      name: designRequirements
    back:
      name: systemRequirements
Domain model type names must be single words without spaces or special characters. Relationship from/to values must reference domainModelTypes names — not Polarion work item type IDs. A “left error” indicates an invalid from entity; a “right error” indicates an invalid to entity.
Related pages: Domain Model Types | Properties | Storage | Sources
KB ArticlesSupport TicketsSource Code
  • prod-powersheet-src/com.nextedy.powersheet.client/cypress/fixtures/configurations/constraints_model.template.yaml
  • prod-powersheet-src/com.nextedy.powersheet.client/cypress/fixtures/models/constraints-base.yaml
  • model.yaml
  • Constraints.java
  • prod-powersheet-src/com.nextedy.powersheet.client/cypress/fixtures/configurations/constraints_currentDocument_downstream.template.yaml