Skip to main content
See also: Domain Model Types | Relationships | Permissions

​
Property Definition Overview

diagram 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

NameTypeDefaultDescription
namestring(required)Property name as exposed in queries and column bindings. Must be unique within the entity type. Automatically derived from the YAML map key.
serverNamestringSame as nameOverride 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.
customFieldNamestringNonePolarion 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.
typestringNoneData type of the property (string, integer, date, etc.). Determines validation and rendering behavior.
storagestringNoneDefines how the property value is persisted in Polarion (e.g., work item field, linked items). Critical for relationship properties.
readablebooleantrueControls whether the property can be read by users. Set to false to hide internal properties. See Permissions.
updatablebooleantrueControls whether the property can be modified by users. Set to false to enforce read-only properties. See Permissions.
scalarbooleantrueIndicates whether property holds a single value (true) or a collection (false). Affects data binding and query expansion.
navigabilitystringNoneDefines 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 domain model property customPriority maps to the Polarion custom field c_priority. In sheet column bindings, you reference the domain 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 domain 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:
PropertyTypeDescription
objectIdstringUnique primary key identifier for the entity instance. Read-only.
idstringPolarion work item ID. Read-only.
titlestringWork 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 domain model YAML.

​
Special Entity Properties

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

​
Document Properties

PropertyTypeDescription
moduleFolderstringPath to the document folder in the repository. Create-only: set during document creation, read-only thereafter.
moduleNamestringDocument file name within its folder. Create-only.
titlestringDocument title displayed in navigation.
typestringDocument type classification.
allowedWITypesarrayWork item types permitted within this document.

​
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:
FlagDefaultEffect when false
readabletrueProperty is hidden from users in the sheet.
updatabletrueProperty 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
PropertyVisibleEditableUse Case
titleYesYesDefault — fully accessible
descriptionYesYesExplicitly set, same as default
severityYesNoUsers can see but not change
internalTrackingIdNoNoCompletely 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 domain 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 domain model YAML.

​
How Navigation Properties Are Generated

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:
AttributeSourceDescription
cardinalityRelationship cardinalityDetermines if the property is scalar (single entity) or collection (multiple entities).
storageRelationship storageHow the link is persisted in Polarion (e.g., linkedWorkItems).
navigabilityRelationship directionWhether the property can be traversed in queries.
scalarDerived from cardinalitytrue 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: 
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 domain model to sheet sources and columns:
CardinalityNavigation PropertySource ExpandColumn BindingUI Behavior
N:1chapter (scalar)- name: chapterchapter, chapter.titleSingle-value reference picker
1:NuserNeeds (collection)- name: userNeedsuserNeedsChild rows (new sheet level)
M:NsystemRequirements (collection)- name: systemRequirements then - name: systemRequirementsystemRequirements.systemRequirementMulti-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 ValueDescriptionUsed For
linkedWorkItemsValue stored as Polarion linked work items.Navigation properties created from relationships.

​
Complete YAML Example

A full domain 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:
TypeDescriptionExample Values
stringText values."Requirements document"
integerWhole number values.42
dateDate or datetime values."2025-01-15"
booleanTrue/false values.true, false
Property type validation behavior depends on the Polarion field definition. The type attribute in the domain 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:
  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: Domain Model Types | Relationships | Constraints | Permissions | Binding Syntax
Support Tickets
  • Data model configuration guidance
Source Code
  • Property.java
  • DomainModelV2.java
  • DomainModelTypeV2.java
  • Relationship.java