Properties

Property Definition Overview

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.

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.
`updatable`	`boolean`	`true`	Controls whether the property can be modified by users. Set to `false` to enforce read-only properties. See 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.

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.

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:

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

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.

Properties with Explicit Configuration

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

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:

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:

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

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.

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.

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.

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.

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.

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

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. Navigation properties represent relationships to other entity types. They are created automatically from Relationships definitions in the data model — they are not declared inline on entity types.

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.

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

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

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

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

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 for the complete syntax reference.

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:

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`

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.

Property Resolution Order

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

customFieldName — if specified, maps directly to the named Polarion custom field.
serverName — if specified, uses this as the Polarion field name instead of the property name.
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 | Relationships | Constraints | Permissions | Binding Syntax

Property Definition Overview

Property Configuration Reference

Defining Properties in YAML

Properties with Explicit Configuration

Custom Field Mapping

Server Name Aliasing

Built-in Properties

Special Entity Properties

Document Properties

Chapter Properties

Property Permissions

Permission Examples

Navigation Properties and Relationships

How Navigation Properties Are Generated

Navigation Property Attributes

Custom Navigation Property Names

Cardinality and Column Binding

Storage Types

Complete YAML Example

Property Type Reference

Property Resolution Order

​Property Definition Overview

​Property Configuration Reference

​Defining Properties in YAML

​Properties with Explicit Configuration

​Custom Field Mapping

​Server Name Aliasing

​Built-in Properties

​Special Entity Properties

​Document Properties

​Chapter Properties

​Property Permissions

​Permission Examples

​Navigation Properties and Relationships

​How Navigation Properties Are Generated

​Navigation Property Attributes

​Custom Navigation Property Names

​Cardinality and Column Binding

​Storage Types

​Complete YAML Example

​Property Type Reference

​Property Resolution Order

Property Definition Overview

Property Configuration Reference

Defining Properties in YAML

Properties with Explicit Configuration

Custom Field Mapping

Server Name Aliasing

Built-in Properties

Special Entity Properties

Document Properties

Chapter Properties

Property Permissions

Permission Examples

Navigation Properties and Relationships

How Navigation Properties Are Generated

Navigation Property Attributes

Custom Navigation Property Names

Cardinality and Column Binding

Storage Types

Complete YAML Example

Property Type Reference

Property Resolution Order