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

# Configure Context Constraints

> Use `$context` expressions in your Nextedy POWERSHEET data model constraints to dynamically filter entities based on the source work item's document properties at runtime, enabling component-scoped relationships.

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>;
};

## Prerequisites

* A working data model with entity types and relationships already defined
* At least one relationship with `direct` and `back` navigation properties configured
* Familiarity with the three constraint stages (`load`, `pick`, `create`) covered in [Configure Constraints](/powersheet/guides/data-model/configure-constraints)

## How Context Expressions Work

A context expression uses the `$context` prefix followed by a dot-notation property path. Powersheet resolves this path at runtime by reading the current row's source entity properties. Unlike static constraint values, context expressions produce **different filter results per row** depending on each source entity's document.

<Frame>
  <img src="https://mintcdn.com/none-17b4493f/3Zik2OH750CE3kB4/powersheet/diagrams/guides/data-model/configure-context-constraints/diagram-1.svg?fit=max&auto=format&n=3Zik2OH750CE3kB4&q=85&s=9ba35a7aa1e8b9abbdc533775596cfdc" alt="diagram" style={{ width: "560px", maxWidth: "100%" }} width="560" height="220" data-path="powersheet/diagrams/guides/data-model/configure-context-constraints/diagram-1.svg" />
</Frame>

<Info title="Context expressions vs. dynamic values">
  Context expressions (`$context.property.path`) are used **only in data model YAML** -- specifically inside `constraints` blocks. They support dot-notation property access but not JavaScript logic. For dynamic expressions in **sheet configuration** YAML (sources, columns, formatters), use the `() => expression` syntax instead. See [Configure Dynamic Expressions](/powersheet/guides/sheet-configuration/configure-dynamic-expressions) for that approach.
</Info>

## Available Context Paths

The `$context` object provides access to the source entity's document properties. These are the paths you can use:

| Path                                    | Description                          | Example Value                       |
| --------------------------------------- | ------------------------------------ | ----------------------------------- |
| `$context.source.type`                  | Source entity's work item type       | `"sys_req"`                         |
| `$context.source.document.id`           | Source entity's document ID          | `"Requirements/SRS"`                |
| `$context.source.document.moduleName`   | Source entity's document module name | `"UserNeedSpecification"`           |
| `$context.source.document.moduleFolder` | Source entity's document folder      | `"Requirements"`                    |
| `$context.source.document.component`    | Source entity's document component   | `"Braking"`                         |
| `$context.source.document.type`         | Source entity's document type        | `"systemRequirementsSpecification"` |
| `$context.source.document.title`        | Source entity's document title       | `"System Requirements"`             |

<Steps>
  <Step title="Filter by Document Component">
    The most common use case is scoping relationship pickers by the source entity's document component. This prevents users from accidentally linking to entities outside their subsystem.

    Add a `$context` reference inside the constraint `document` block on the appropriate relationship direction:

    ```yaml theme={null}
    relationships:
      - from: DesignRequirement
        to: SystemRequirement
        cardinality: many-to-many
        storage: linkedWorkItems
        linkRole: satisfies
        direct:
          name: systemRequirements
        back:
          name: designRequirements
          constraints:
            load:
              document:
                component: $context.source.document.component
    ```

    With this constraint, when viewing a `SystemRequirement` in a document with component "Braking", only `DesignRequirement` items from "Braking" documents will be loaded as children.
  </Step>

  <Step title="Filter by Document Name and Folder">
    To restrict linked items to the exact same document as the source entity, combine `moduleName` and `moduleFolder`:

    ```yaml theme={null}
    constraints:
      load:
        document:
          moduleName: $context.source.document.moduleName
          moduleFolder: $context.source.document.moduleFolder
    ```

    This pattern is useful in projects where each document represents a self-contained specification, and traceability should stay within document boundaries.
  </Step>

  <Step title="Apply Context Constraints to Pick and Create Stages">
    Context expressions work across all three constraint stages. Apply them to `pick` to scope the relationship picker dialog, or to `create` to control where new items are created:

    ```yaml theme={null}
    relationships:
      - from: Hazard
        to: UserNeed
        cardinality: many-to-many
        storage: linkedWorkItems
        linkRole: mitigates
        direct:
          name: userNeeds
        back:
          name: hazards
          constraints:
            load:
              document:
                component: $context.source.document.component
            pick:
              document:
                type: $context.source.document.type
            create:
              document:
                moduleFolder: $context.source.document.moduleFolder
    ```

    In this configuration:

    * **load**: only hazards from the same component appear in the sheet
    * **pick**: the picker shows items from documents of the same type as the source
    * **create**: new hazards are created in the same folder as the source document

    <Tip title="Stage cascading with context expressions">
      The same cascading rules apply to context constraints as to static constraints. The `pick` stage inherits `load` constraints, and `create` inherits both `load` and `pick`. You only need to define the additional filter at each stage.
    </Tip>
  </Step>

  <Step title="Apply Context Constraints at Entity Type Level">
    Context expressions can also be placed on `domainModelTypes` entries (not just relationships). This applies the constraint globally whenever that entity type is loaded, picked, or created:

    ```yaml theme={null}
    domainModelTypes:
      SystemRequirement:
        polarionType: sys_req
        properties:
          description:
          severity:
        constraints:
          pick:
            document:
              component: $context.source.document.component
    ```

    <Warning title="Entity-level vs. relationship-level constraints">
      When both the entity type and a relationship define constraints, both are applied. If they conflict (for example, the entity constraint specifies one component and the relationship constraint specifies a different filter), the intersection may produce an empty result set. Place context constraints at either the entity type **or** the relationship level, not both, unless you intentionally need combined filtering.
    </Warning>
  </Step>

  <Step title="Combine Context and Static Constraints">
    You can mix `$context` expressions with static values in the same constraint block. Static values act as fixed filters while context values adapt per row:

    ```yaml theme={null}
    constraints:
      pick:
        document:
          type: systemRequirementsSpecification
          component: $context.source.document.component
    ```

    This restricts the picker to items that are both in `systemRequirementsSpecification` documents **and** in the same component as the source entity's document.
  </Step>
</Steps>

## Common Patterns

| Scenario              | Context Path                            | Constraint Example                                    |
| --------------------- | --------------------------------------- | ----------------------------------------------------- |
| Same component        | `$context.source.document.component`    | `component: $context.source.document.component`       |
| Same document         | `$context.source.document.moduleName`   | `moduleName: $context.source.document.moduleName`     |
| Same folder           | `$context.source.document.moduleFolder` | `moduleFolder: $context.source.document.moduleFolder` |
| Same document type    | `$context.source.document.type`         | `type: $context.source.document.type`                 |
| Same document (exact) | `$context.source.document.id`           | `id: $context.source.document.id`                     |

## Complete YAML Example

Below is a full data model snippet demonstrating context constraints across entity types and relationships in a standard RTM hierarchy:

```yaml theme={null}
domainModelTypes:
  UserNeed:
    polarionType: user_need
    properties:
      description:
      severity:

  SystemRequirement:
    polarionType: sys_req
    properties:
      description:
      severity:

  DesignRequirement:
    polarionType: des_req
    properties:
      description:

  RiskControl:
    polarionType: risk_control
    properties:
      description:

relationships:
  - from: SystemRequirement
    to: UserNeed
    cardinality: many-to-many
    storage: linkedWorkItems
    linkRole: decomposes
    direct:
      name: userNeeds
    back:
      name: systemRequirements
      constraints:
        load:
          document:
            component: $context.source.document.component
        pick:
          document:
            component: $context.source.document.component
            type: systemRequirementsSpecification

  - from: DesignRequirement
    to: SystemRequirement
    cardinality: many-to-many
    storage: linkedWorkItems
    linkRole: satisfies
    direct:
      name: systemRequirements
    back:
      name: designRequirements
      constraints:
        load:
          document:
            component: $context.source.document.component

  - from: RiskControl
    to: DesignRequirement
    cardinality: many-to-many
    storage: linkedWorkItems
    linkRole: mitigates
    direct:
      name: designRequirements
      constraints:
        pick:
          document:
            moduleFolder: $context.source.document.moduleFolder
    back:
      name: riskControls
```

## Verification

After saving the data model with context constraints:

1. Open a sheet that uses this data model
2. Navigate to a row whose source entity belongs to a specific document component (e.g., "Braking")
3. For **load** constraints: verify that child rows show only entities from the same component
4. For **pick** constraints: click a relationship picker cell and confirm the dropdown shows only items matching the source entity's document properties
5. Compare two rows from different components -- each should show different filtered results based on its own source entity context

You should now see context-sensitive filtering where each row's constraints resolve independently based on its source entity's document properties. If all rows show the same results regardless of component, verify that:

* The `$context` path is spelled correctly (case-sensitive)
* Source entities actually have different document component/folder values in Polarion
* The constraint is placed on the correct relationship direction (`direct` or `back`)

<Warning title="Empty picker results">
  If a source entity's document has no `component` value set in Polarion, a constraint using `$context.source.document.component` will resolve to an empty string, which typically matches no items. Ensure your Polarion documents have the relevant properties populated before relying on context constraints.
</Warning>

## See Also

* [Configure Constraints](/powersheet/guides/data-model/configure-constraints) -- static constraint stages, operators, and logical composition
* [Configure a Relationship](/powersheet/guides/data-model/configure-relationship) -- setting up the relationships that context constraints filter
* [Configure Dynamic Expressions](/powersheet/guides/sheet-configuration/configure-dynamic-expressions) -- `() => expression` syntax for sheet configuration YAML
* [Data Model Reference](/powersheet/reference/data-model/index) -- complete property reference for data model YAML
* [Create Bidirectional Links](/powersheet/guides/data-model/create-bidirectional-links) -- establishing the `direct` and `back` navigation properties used in constraints

<LastReviewed date="2026-06-30" />