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

# Permissions

> Permissions in Nextedy POWERSHEET control access at multiple levels within the data model.

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: [Properties](/powersheet/reference/data-model/properties) | [Data Model Types](/powersheet/reference/data-model/domainmodeltypes) | [Relationships](/powersheet/reference/data-model/relationships)

## Permission Architecture

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

Powersheet permissions operate at two distinct levels within the data model YAML:

1. **Property-level** -- the `readable` and `updatable` flags on each property definition within an entity type
2. **Navigation property-level** -- permission settings on the `direct` and `back` objects within relationship definitions

Both levels use the same two boolean flags to control access.

## Property-Level Permissions

Individual properties on entity types support `readable` and `updatable` flags that control field-level access. These flags are set within the data model YAML under each entity type's `properties` map.

### Permission Flags

| Name        | Type      | Default | Description                                                                                                                                                                                                                                            |
| ----------- | --------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `readable`  | `boolean` | `true`  | Controls whether the property is visible. When set to `false`, the property is excluded from the data payload entirely -- it is not loaded from the server and not transmitted to the client. This provides data-level security, not merely UI hiding. |
| `updatable` | `boolean` | `true`  | Controls whether the property can be modified by users. When set to `false`, the property appears in the sheet as read-only. Users can view the value but cannot change it.                                                                            |

<Warning title="Hidden properties are excluded from data">
  Setting `readable: false` does **not** simply hide a column in the UI. The property is completely excluded from the data payload sent to the client. This means the value is never loaded, never transmitted, and never available to column bindings, queries, or client-side logic. Use this for properties that contain sensitive data or internal identifiers that should not leave the server.
</Warning>

### Permission Combinations

| `readable` | `updatable` | Result                                                                                                                                        |
| ---------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `true`     | `true`      | Property is visible and editable (default behavior).                                                                                          |
| `true`     | `false`     | Property is visible but read-only. Users can see the value but cannot modify it. Useful for computed fields, audit stamps, or reference data. |
| `false`    | `true`      | Property is hidden from the client entirely. The `updatable` flag has no practical effect since the property is not transmitted.              |
| `false`    | `false`     | Property is hidden from the client entirely. Equivalent to `readable: false` alone.                                                           |

<Tip title="Read-only columns vs. read-only properties">
  The `isReadOnly` flag on a [column definition](/powersheet/reference/sheet-config/columns) controls whether a specific column is editable in the sheet UI. The `updatable` flag on a **property** controls whether the underlying data field can be modified at all. If `updatable: false` is set on the property, the field is read-only regardless of the column's `isReadOnly` setting.
</Tip>

## Configuring Property Permissions in YAML

### Basic Example

Properties without explicit permission flags inherit the defaults (`readable: true`, `updatable: true`):

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

All three properties above are visible and editable.

### Mixed Permissions Example

Apply explicit permission flags to restrict individual properties:

```yaml theme={null}
domainModelTypes:
  UserNeed:
    polarionType: user_need
    properties:
      id:
        readable: true
        updatable: false
      title:
        readable: true
        updatable: true
      outlineNumber:
        readable: true
        updatable: false
      description:
      severity:
```

In this configuration:

* `id` -- visible but cannot be edited (system identifier)
* `title` -- explicitly set to visible and editable (same as default)
* `outlineNumber` -- explicitly declared and marked visible but read-only (managed automatically by Polarion)
* `description` and `severity` -- inherit defaults (visible and editable)

### Hiding Sensitive Properties

To prevent a property from being transmitted to the client at all, set `readable: false`:

```yaml theme={null}
domainModelTypes:
  UserNeed:
    polarionType: user_need
    properties:
      title:
      description:
      severity:
      internalClassification:
        readable: false
```

The `internalClassification` property is completely excluded from the data payload. No column binding can reference it, and it does not appear in query results returned to the client.

## Built-in Property Permissions

Certain properties have inherent permission characteristics based on their role in the Polarion data model. The following table lists common built-in properties and their typical permission settings:

| Property      | Typical `readable` | Typical `updatable` | Notes                                                      |
| ------------- | ------------------ | ------------------- | ---------------------------------------------------------- |
| `id`          | `true`             | `false`             | Work item identifier. System-managed, never user-editable. |
| `title`       | `true`             | `true`              | Work item title. Usually editable.                         |
| `description` | `true`             | `true`              | Standard text property. Editable by default.               |
| `severity`    | `true`             | `true`              | Enumeration property. Editable by default.                 |

<Note title="`outlineNumber` is not a built-in property">
  Unlike `id` and `title`, `outlineNumber` is **not** an implicit built-in property of every entity type. To use it, you must explicitly declare it in the entity type's `properties` map in your data model YAML. When declared, it is typically configured as `readable: true, updatable: false` because its value is managed automatically by Polarion based on the document hierarchy.
</Note>

<Info title="Verify in application">
  Built-in property behavior may vary depending on the Polarion version and project configuration. Verify the exact behavior of each built-in property in your environment.
</Info>

## Entity Types and Permission Scoping

Permission flags are scoped to each entity type independently. The same property name can have different permissions on different entity types:

```yaml theme={null}
domainModelTypes:
  UserNeed:
    polarionType: user_need
    properties:
      severity:
        readable: true
        updatable: true

  SystemRequirement:
    polarionType: sys_req
    properties:
      severity:
        readable: true
        updatable: false
```

In this example, `severity` is editable on `UserNeed` entities but read-only on `SystemRequirement` entities.

### Special Entity Types

| Entity Type | Purpose                                                 | Permission Notes                                                                                                   |
| ----------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `Document`  | Built-in entity for Polarion LiveDocs                   | Supports mixed permission settings on properties. Useful for controlling which document-level fields are editable. |
| `Chapter`   | Entity type mapped to Polarion `heading` work item type | Properties are typically read-only since headings are structural elements.                                         |
| `Project`   | Built-in entity for Polarion project metadata           | Minimal property definitions. Permissions rarely customized.                                                       |

## Navigation Property Permissions

Relationships in the data model define navigation properties that allow traversal between entity types. Each relationship has a `direct` and optionally a `back` direction, and each direction can carry its own permission settings.

<Info title="Feature under active rework">
  The navigation property permission system is under active development. The behavior described below reflects the current implementation, but changes are expected. Updated documentation will follow as the feature stabilizes.
</Info>

### Navigation Direction Properties

| Name          | Type      | Default         | Description                                                                                  |
| ------------- | --------- | --------------- | -------------------------------------------------------------------------------------------- |
| `direct.name` | `string`  | *(required)*    | Name of the forward navigation property on the source entity.                                |
| `back.name`   | `string`  | *(optional)*    | Name of the reverse navigation property on the target entity.                                |
| `createable`  | `boolean` | See application | Controls whether new relationship instances can be created through this navigation property. |
| `readable`    | `boolean` | See application | Controls whether the navigation property is visible in queries and data payloads.            |

### Relationship YAML with Navigation Directions

```yaml theme={null}
relationships:
  - from: UserNeed
    to: Chapter
    cardinality: many-to-one
    storage: linkedWorkItems
    linkRole: parent
    direct:
      name: chapter
    back:
      name: userNeeds

  - from: SystemRequirement
    to: UserNeed
    cardinality: many-to-many
    storage: linkedWorkItems
    linkRole: decomposes
    direct:
      name: userNeeds
    back:
      name: systemRequirements
```

The `direct` object defines the forward navigation property (from source to target), while the `back` object defines the reverse navigation property (from target back to source). Each can have independent permission settings that control whether the navigation path is available and whether new links can be created through it.

## Read-Only Mode

The sheet can enter a global read-only mode through several mechanisms. When read-only mode is active, all properties behave as if `updatable: false` regardless of their individual settings.

| Condition                             | Effect                                        |
| ------------------------------------- | --------------------------------------------- |
| Configuration `isReadOnly` is `true`  | Entire sheet is read-only.                    |
| User is viewing a historical revision | Sheet is read-only (revisions are immutable). |
| License status is `INVALID`           | Restricted access; sheet is read-only.        |

<Warning title="Read-only mode overrides property permissions">
  When any of the conditions above is met, the sheet enters read-only mode. Individual `updatable: true` settings on properties are overridden. The sheet displays all readable properties but prevents any modifications.
</Warning>

## Permission Decision Flow

The following table summarizes how the final editability of a field is determined:

| Check                   | Condition                                                    | Result                                      |
| ----------------------- | ------------------------------------------------------------ | ------------------------------------------- |
| 1. Global read-only     | `isReadOnly` config, historical revision, or invalid license | All fields read-only                        |
| 2. Property `readable`  | `false`                                                      | Property excluded from data payload         |
| 3. Property `updatable` | `false`                                                      | Property visible but not editable           |
| 4. Column `isReadOnly`  | `true`                                                       | Column display is read-only in the sheet UI |
| 5. All checks pass      | --                                                           | Field is visible and editable               |

Checks are evaluated in order. A `false` result at any step short-circuits subsequent checks for that field.

## Complete YAML Example

A data model demonstrating permission controls across multiple entity types with varied access levels:

```yaml theme={null}
domainModelTypes:
  Chapter:
    polarionType: heading
    properties:
      title:
        readable: true
        updatable: false

  UserNeed:
    polarionType: user_need
    properties:
      id:
        readable: true
        updatable: false
      title:
        readable: true
        updatable: true
      outlineNumber:
        readable: true
        updatable: false
      description:
      severity:
      internalNotes:
        readable: false

  SystemRequirement:
    polarionType: sys_req
    properties:
      id:
        readable: true
        updatable: false
      title:
      description:
      severity:
        readable: true
        updatable: false

  DesignRequirement:
    polarionType: des_req
    properties:
      title:
      description:

relationships:
  - from: UserNeed
    to: Chapter
    cardinality: many-to-one
    storage: linkedWorkItems
    linkRole: parent
    direct:
      name: chapter
    back:
      name: userNeeds

  - from: SystemRequirement
    to: UserNeed
    cardinality: many-to-many
    storage: linkedWorkItems
    linkRole: decomposes
    direct:
      name: userNeeds
    back:
      name: systemRequirements
```

This example demonstrates:

* **`Chapter.title`** -- visible but read-only (structural headings should not be edited through the sheet)
* **`UserNeed.id`** -- visible but read-only (system identifier)
* **`UserNeed.outlineNumber`** -- explicitly declared as visible but read-only (auto-managed by Polarion; this property must be declared explicitly to appear in the model)
* **`UserNeed.internalNotes`** -- hidden entirely (`readable: false`); never transmitted to the client
* **`SystemRequirement.severity`** -- visible but read-only (locked for this entity type)
* **`DesignRequirement`** properties -- all defaults (visible and editable)

## Best Practices

| Practice               | Recommendation                                                                                                                                                                                         |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Sensitive data         | Use `readable: false` to prevent transmission to the client. Do not rely on column visibility alone.                                                                                                   |
| Audit fields           | Set `updatable: false` on explicitly declared fields like `id`, `outlineNumber`, and timestamp fields that should not be manually edited.                                                              |
| Progressive disclosure | Use [Views](/powersheet/reference/sheet-config/views) to control which columns are visible in different analysis perspectives, rather than using `readable: false` which removes data access entirely. |
| Consistent naming      | Keep property names aligned across entity types when they serve the same purpose (e.g., `severity` on both `UserNeed` and `SystemRequirement`).                                                        |
| Testing permissions    | Verify permission behavior in a test project before deploying to production. Check that hidden properties are truly absent from server responses.                                                      |

<Tip title="Views for visibility, permissions for security">
  Use [Views](/powersheet/reference/sheet-config/views) when you want to show or hide columns for different user workflows -- the data is still loaded but specific columns are toggled. Use `readable: false` when the data itself must not leave the server.
</Tip>

***

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