> ## Documentation Index
> Fetch the complete documentation index at: https://learn.nextedy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Constraints

> Constraints in the Nextedy POWERSHEET data model define data scoping rules for entity types.

export const LastReviewed = ({date}) => {
  if (!date) return null;
  const formatted = new Date(`${date}T00:00:00Z`).toLocaleDateString("en-US", {
    year: "numeric",
    month: "long",
    day: "numeric",
    timeZone: "UTC"
  });
  return <p className="mt-10 text-sm text-gray-400 dark:text-zinc-500 not-prose">
      Last reviewed on {formatted}
    </p>;
};

See also: [Data Model Types](/powersheet/reference/data-model/domainmodeltypes) | [Properties](/powersheet/reference/data-model/properties) | [Relationships](/powersheet/reference/data-model/relationships) | [Cardinality](/powersheet/reference/data-model/cardinality)

## Constraint Stages Overview

<Frame>
  <img src="https://mintcdn.com/none-17b4493f/-WiVljKlDztH36bB/powersheet/diagrams/reference/data-model/constraints/diagram-1.svg?fit=max&auto=format&n=-WiVljKlDztH36bB&q=85&s=f893c827ce303da7f1e19aeaf560645f" alt="diagram" style={{ width: "600px", maxWidth: "100%" }} width="600" height="280" data-path="powersheet/diagrams/reference/data-model/constraints/diagram-1.svg" />
</Frame>

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)

<Info title="Fallback rule">
  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.
</Info>

<Tip title="Practical effect of cascading">
  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.
</Tip>

## 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. All standard document metadata fields are constrainable.

| Name                    | Type     | Default | Description                                                                                                                                        |
| ----------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `document`              | `object` | None    | Document-based constraint object. Scopes entities to work items within specific LiveDoc documents.                                                 |
| `document.moduleFolder` | `string` | None    | Polarion space (module folder) containing the document, e.g., `"Requirements"` or `"Risks"`. Supports comparison operators.                        |
| `document.moduleName`   | `string` | None    | Polarion document name (module name) within the space. Supports comparison operators.                                                              |
| `document.type`         | `string` | None    | Document type identifier (e.g., `req_specification`, `risk_analysis`). Supports comparison operators.                                              |
| `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.                             |
| `document.component`    | `string` | None    | Component or category assigned to the document. Useful for scoping by product component or sub-system. Supports comparison operators.              |

<Tip title="Constrainable document properties">
  All document metadata fields -- `moduleFolder`, `moduleName`, `type`, `id`, `title`, and `component` -- can be used in constraint expressions. Combine them within a single `document` block to express precise scoping rules (for example, constraining by space and document type together).
</Tip>

### 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" }`        |

<Note title="Default operator">
  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.
</Note>

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

```yaml theme={null}
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:

```yaml theme={null}
domainModelTypes:
  SystemRequirement:
    polarionType: sys_req
    constraints:
      load:
        document:
          id:
            in: [Requirements, SafetyRequirements]
        # Result: document.id = "Requirements" OR document.id = "SafetyRequirements"
```

<Tip title="Combining AND and OR">
  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.
</Tip>

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

```yaml theme={null}
domainModelTypes:
  UserNeed:
    polarionType: user_need
    constraints:
      load:
        document:
          id: $currentDocument.id
      pick:
        document:
          id: $currentDocument.id
```

This configuration ensures that only work items from the currently viewed document are loaded into the sheet and shown in pickers.

<Info title="Verify in application">
  The full list of available context variables may extend beyond `$currentDocument`. Consult the application release notes for the latest supported context expressions.
</Info>

For more on context expressions in queries, see [Context Expressions Reference](/powersheet/reference/data-model/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

```yaml theme={null}
domainModelTypes:
  DesignRequirement:
    polarionType: des_req
    constraints:
      load:
        document:
          id: $currentDocument.id
      pick:
        status:
          in: [approved, reviewed]
      create:
        severity: medium
```

**Effective constraints at each stage:**

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

<Warning title="Conflicting constraints">
  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.
</Warning>

## Complete YAML Examples

### Load-Only Constraint

Restrict an entity type to only show work items from a specific document:

```yaml theme={null}
domainModelTypes:
  UserNeed:
    polarionType: user_need
    properties:
      description:
      severity:
    constraints:
      load:
        document:
          id: Requirements
```

**Effect**: Only `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:

```yaml theme={null}
domainModelTypes:
  SystemRequirement:
    polarionType: sys_req
    properties:
      description:
      severity:
    constraints:
      pick:
        status:
          in: [approved, reviewed]
```

**Effect**: All `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:

```yaml theme={null}
domainModelTypes:
  Hazard:
    polarionType: hazard
    properties:
      severity:
      status:
    constraints:
      create:
        severity: low
        status: draft
```

**Effect**: All hazards load normally and all appear in pickers. Newly created hazards default to `severity: low` and `status: draft`.

### Current-Document Scoping

Dynamically scope all stages to the currently open document:

```yaml theme={null}
domainModelTypes:
  UserNeed:
    polarionType: user_need
    properties:
      description:
      severity:
    constraints:
      load:
        document:
          id: $currentDocument.id
      pick:
        document:
          id: $currentDocument.id
      create:
        document:
          id: $currentDocument.id
```

**Effect**: Loading, picking, and creation are all scoped to the document currently open in Polarion. This is the most common pattern for document-centric sheets.

### Multi-Stage Composition

A complete example combining all three stages with different scoping:

```yaml theme={null}
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
```

**Effect**:

* `UserNeed` items load from the current document, pickers show only approved/reviewed/draft items from that document, and new items default to `severity: medium`
* `SystemRequirement` 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](/powersheet/reference/data-model/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`  |

For details on how cardinality affects column bindings, see [Cardinality](/powersheet/reference/data-model/cardinality). For details on column binding syntax, see [Binding Syntax](/powersheet/reference/sheet-config/binding-syntax).

<Tip title="Relationship picker filtering">
  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.
</Tip>

## Sheet-Level Constraints

In addition to data 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.

```yaml theme={null}
sources:
  - id: user_needs
    query:
      from: UserNeed
    expand:
      - name: chapter
```

Source-level filtering and data model constraints work together:

* **Data 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](/powersheet/reference/sheet-config/sources). For query filtering options, see [EntityQuery](/powersheet/reference/query-api/entity-query) and [Document Filtering](/powersheet/reference/query-api/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      |

***

<LastReviewed date="2026-07-02" />