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

# Properties

> Properties define the fields available on each entity type in a Nextedy POWERSHEET 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: [Data Model Types](/powersheet/reference/data-model/domainmodeltypes) | [Relationships](/powersheet/reference/data-model/relationships) | [Permissions](/powersheet/reference/data-model/permissions)

## Property Definition Overview

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

Each entity type contains a `properties` map. Each entry defines a field name, its mapping to Polarion storage, and optional access controls. Properties are resolved at runtime through the metadata system and exposed to sheet columns via [binding paths](/powersheet/reference/sheet-config/binding-syntax).

## Property Configuration Reference

| Name              | Type      | Default        | Description                                                                                                                                                                    |
| ----------------- | --------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `name`            | `string`  | *(required)*   | Property name as exposed in queries and column bindings. Must be unique within the entity type. Automatically derived from the YAML map key.                                   |
| `serverName`      | `string`  | Same as `name` | Override for the actual Polarion field name when it differs from the client-facing property name. Allows aliasing Polarion field names to more user-friendly names.            |
| `customFieldName` | `string`  | None           | Polarion custom field ID for properties stored in custom fields. Required when the property maps to a custom field rather than a built-in work item field.                     |
| `type`            | `string`  | None           | Data type of the property (`string`, `integer`, `date`, etc.). Determines validation and rendering behavior.                                                                   |
| `storage`         | `string`  | None           | Defines how the property value is persisted in Polarion (e.g., work item field, linked items). Critical for relationship properties.                                           |
| `readable`        | `boolean` | `true`         | Controls whether the property can be read by users. Set to `false` to hide internal properties. See [Permissions](/powersheet/reference/data-model/permissions).               |
| `updatable`       | `boolean` | `true`         | Controls whether the property can be modified by users. Set to `false` to enforce read-only properties. See [Permissions](/powersheet/reference/data-model/permissions).       |
| `scalar`          | `boolean` | `true`         | Indicates whether property holds a single value (`true`) or a collection (`false`). Affects data binding and query expansion.                                                  |
| `navigability`    | `string`  | None           | Defines navigation direction for relationship properties (`unidirectional`, `bidirectional`). Controls whether relationships can be traversed in queries using expand clauses. |

<Warning title="Name uniqueness">
  Property names must be unique within each entity type. The `name` field is automatically set from the YAML map key -- you do not need to specify it explicitly.
</Warning>

## Defining Properties in YAML

Properties are declared within each entity type under the `properties` key. The simplest form uses a null value (empty after the colon) to declare that a property exists with default settings:

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

<Tip title="Null values">
  A property set to `null` (or left empty after the colon) inherits all default settings. The property name is used as the Polarion field name unless `serverName` or `customFieldName` is specified.
</Tip>

### Properties with Explicit Configuration

When a property requires non-default settings, provide an object with the desired attributes:

```yaml theme={null}
domainModelTypes:
  SystemRequirement:
    polarionType: sys_req
    properties:
      title:
      description:
      severity:
      internalNotes:
        readable: false
        updatable: false
```

In this example, `internalNotes` is hidden from users (not readable) and cannot be modified (not updatable). The remaining properties (`title`, `description`, `severity`) use default settings.

### Custom Field Mapping

When a property maps to a Polarion custom field rather than a built-in field, use `customFieldName` to specify the Polarion custom field ID:

```yaml theme={null}
domainModelTypes:
  UserNeed:
    polarionType: user_need
    properties:
      title:
      description:
      customPriority:
        customFieldName: c_priority
```

Here, the data model property `customPriority` maps to the Polarion custom field `c_priority`. In sheet column bindings, you reference the data model name (`customPriority`), not the Polarion field name.

### Server Name Aliasing

Use `serverName` when the Polarion built-in field name differs from the name you want to expose in the data model:

```yaml theme={null}
domainModelTypes:
  UserNeed:
    polarionType: user_need
    properties:
      title:
      itemStatus:
        serverName: status
```

The property is referenced as `itemStatus` in column bindings and queries, but resolves to the Polarion `status` field on the server.

## Built-in Properties

All work item entity types automatically include these built-in properties without explicit declaration:

| Property   | Type     | Description                                                                            |
| ---------- | -------- | -------------------------------------------------------------------------------------- |
| `objectId` | `string` | Unique primary key identifier for the entity instance. Read-only.                      |
| `id`       | `string` | Polarion work item ID. Read-only.                                                      |
| `title`    | `string` | Work item title. Applies to work item entity types only (not `Document` or `Chapter`). |

<Info title="Implicit availability">
  Built-in properties are available on every work item entity type even if not listed in the `properties` map. You can reference them in column bindings (e.g., `id`, `title`) without declaring them in the data model YAML.
</Info>

## Special Entity Properties

The built-in `Document` and `Chapter` entity types have specialized property behavior distinct from work item entities.

### Document Properties

| Property         | Type                         | Description                                                                                                               |
| ---------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `moduleFolder`   | `string`                     | Path to the document folder in the repository. Create-only: set during document creation, read-only thereafter.           |
| `moduleName`     | `string`                     | Document file name within its folder. Create-only.                                                                        |
| `title`          | `string`                     | Document title displayed in navigation.                                                                                   |
| `titleOrName`    | `string`                     | Document title when available, otherwise falls back to the module name. Convenient display field when `title` is not set. |
| `titleWithSpace` | `string`                     | Document title formatted with a leading or padded space, used for display alignment in navigation contexts.               |
| `type`           | `string`                     | Document type classification.                                                                                             |
| `allowedWITypes` | `string` (scalar by default) | Work item types permitted within this document.                                                                           |

<Note title="Multi-valued `allowedWITypes`">
  `allowedWITypes` is scalar by default (a single string). To treat it as a list of multiple permitted work item types, explicitly override `scalar: false` on this property in the data model YAML.
</Note>

### Chapter Properties

The `Chapter` entity type maps to Polarion headings (`polarionType: heading`). Chapters represent structural elements in a document hierarchy and are typically used as grouping nodes in expansion paths.

```yaml theme={null}
domainModelTypes:
  Chapter:
    polarionType: heading
```

Chapters do not require explicit property declarations. They inherit the standard built-in properties and serve primarily as navigation anchors in [relationships](/powersheet/reference/data-model/relationships).

## Property Permissions

Each property supports two permission flags that control field-level access:

| Flag        | Default | Effect when `false`                                     |
| ----------- | ------- | ------------------------------------------------------- |
| `readable`  | `true`  | Property is hidden from users in the sheet.             |
| `updatable` | `true`  | Property is read-only -- users cannot modify the value. |

### Permission Examples

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

| Property             | Visible | Editable | Use Case                         |
| -------------------- | ------- | -------- | -------------------------------- |
| `title`              | Yes     | Yes      | Default -- fully accessible      |
| `description`        | Yes     | Yes      | Explicitly set, same as default  |
| `severity`           | Yes     | No       | Users can see but not change     |
| `internalTrackingId` | No      | No       | Completely hidden from the sheet |

For more details on permission inheritance through relationships, see [Permissions](/powersheet/reference/data-model/permissions).

## Navigation Properties and Relationships

Navigation properties represent relationships to other entity types. They are **created automatically** from [Relationships](/powersheet/reference/data-model/relationships) definitions in the data model -- they are not declared inline on entity types.

<Info title="Verify in application">
  Navigation properties are always derived from `relationships` definitions. To create a navigation property between two entity types, define the relationship in the `relationships` section of the data model YAML.
</Info>

### How Navigation Properties Are Generated

When a relationship is defined, Powersheet automatically creates navigation properties on both sides:

```yaml theme={null}
relationships:
  - from: UserNeed
    to: SystemRequirement
    cardinality: many-to-many
    storage: linkedWorkItems
    linkRole: decomposes
    direct:
      name: userNeeds
    back:
      name: systemRequirements
```

This creates:

* `userNeeds` navigation property on `SystemRequirement` (the `direct` side)
* `systemRequirements` navigation property on `UserNeed` (the `back` side)

Navigation property names are specified in the `direct.name` and `back.name` fields of the relationship definition.

### Navigation Property Attributes

Navigation properties inherit several attributes from their parent relationship:

| Attribute      | Source                     | Description                                                                             |
| -------------- | -------------------------- | --------------------------------------------------------------------------------------- |
| `cardinality`  | Relationship `cardinality` | Determines if the property is scalar (single entity) or collection (multiple entities). |
| `storage`      | Relationship `storage`     | How the link is persisted in Polarion (e.g., `linkedWorkItems`).                        |
| `navigability` | Relationship direction     | Whether the property can be traversed in queries.                                       |
| `scalar`       | Derived from cardinality   | `true` for many-to-one (direct side), `false` for one-to-many and many-to-many.         |

### Custom Navigation Property Names

Use `direct` and `back` on the relationship to override default navigation property names:

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

Here, navigating from `UserNeed` to `Chapter` uses the property name `chapter` (scalar, N:1), while the reverse uses `userNeeds` (collection, 1:N).

## Cardinality and Column Binding

The cardinality of a relationship determines the expand pattern and column binding syntax. This table summarizes how properties connect the data model to sheet sources and columns:

| Cardinality | Navigation Property               | Source Expand                                                 | Column Binding                         | UI Behavior                   |
| ----------- | --------------------------------- | ------------------------------------------------------------- | -------------------------------------- | ----------------------------- |
| **N:1**     | `chapter` (scalar)                | `- name: chapter`                                             | `chapter`, `chapter.title`             | Single-value reference picker |
| **1:N**     | `userNeeds` (collection)          | `- name: userNeeds`                                           | `userNeeds`                            | Child rows (new sheet level)  |
| **M:N**     | `systemRequirements` (collection) | `- name: systemRequirements` then `- name: systemRequirement` | `systemRequirements.systemRequirement` | Multi-item reference picker   |

<Tip title="Dot-notation for nested access">
  Use dot-notation in column bindings to access properties on related entities. For example, `chapter.title` displays the `title` property of the related `Chapter` entity. See [Binding Syntax](/powersheet/reference/sheet-config/binding-syntax) for the complete syntax reference.
</Tip>

## Storage Types

The `storage` attribute on a property determines how the value is persisted in Polarion:

| Storage Value     | Description                                 | Used For                                          |
| ----------------- | ------------------------------------------- | ------------------------------------------------- |
| `linkedWorkItems` | Value stored as Polarion linked work items. | Navigation properties created from relationships. |

## Complete YAML Example

A full data model demonstrating data properties, custom fields, permissions, and relationships:

```yaml theme={null}
domainModelTypes:
  Document:
    properties:
      title:
      type:

  Chapter:
    polarionType: heading

  UserNeed:
    polarionType: user_need
    properties:
      title:
      description:
      severity:
      component:

  SystemRequirement:
    polarionType: sys_req
    properties:
      title:
      description:
      severity:
      customPriority:
        customFieldName: c_priority
      internalNotes:
        readable: false
        updatable: false

  DesignRequirement:
    polarionType: des_req
    properties:
      title:
      description:
      severity:

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 model defines five entity types with their properties and two relationships. The `SystemRequirement` type includes a custom field mapping (`customPriority` mapped to Polarion custom field `c_priority`) and a hidden property (`internalNotes`). Navigation properties (`chapter`, `userNeeds`, `systemRequirements`) are generated automatically from the relationship definitions.

## Property Type Reference

The `type` attribute accepts the following values:

| Type      | Description              | Example Values            |
| --------- | ------------------------ | ------------------------- |
| `string`  | Text values.             | `"Requirements document"` |
| `integer` | Whole number values.     | `42`                      |
| `date`    | Date or datetime values. | `"2025-01-15"`            |
| `boolean` | True/false values.       | `true`, `false`           |

<Info title="Verify in application">
  Property type validation behavior depends on the Polarion field definition. The `type` attribute in the data model is primarily informational for the metadata system. Actual validation is enforced by Polarion's field configuration.
</Info>

## Property Resolution Order

When Powersheet resolves a property name to a Polarion field, it follows this order:

1. **`customFieldName`** -- if specified, maps directly to the named Polarion custom field.
2. **`serverName`** -- if specified, uses this as the Polarion field name instead of the property name.
3. **Property name** -- if neither override is specified, the property name is used directly as the Polarion field name.

```
Property "customPriority"
  customFieldName: c_priority  -->  Polarion field: c_priority

Property "itemStatus"
  serverName: status           -->  Polarion field: status

Property "title"
  (no overrides)               -->  Polarion field: title
```

***

**Related pages:** [Data Model Types](/powersheet/reference/data-model/domainmodeltypes) | [Relationships](/powersheet/reference/data-model/relationships) | [Constraints](/powersheet/reference/data-model/constraints) | [Permissions](/powersheet/reference/data-model/permissions) | [Binding Syntax](/powersheet/reference/sheet-config/binding-syntax)

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