Data Model Types - Nextedy Documentation

Top-Level Structure

domainModelTypes is defined as a map where each key is the entity type name and the value is the type definition object:

domainModelTypes:
  UserNeed:
    polarionType: user_need
    properties:
      description:
      severity:
  SystemRequirement:
    polarionType: sys_req
    properties:
      description:
      component:

The map key becomes the entity type name automatically. When the data model is loaded, Powersheet copies each map key into the corresponding type object so the name is consistently available regardless of how the type is accessed.

domainModelTypes must be a YAML map. Array format is not supported.

Entity Type Diagram

Entity Type Configuration Properties

Property	Type	Default	Description
`name`	`string`	Derived from map key	Unique identifier for the entity type. Set automatically from the YAML map key. Referenced by `relationships[].from` and `relationships[].to`.
`pluralName`	`string`	Auto-generated from `name`	Plural form of the entity type name. Auto-generated using standard English pluralization if not specified.
`polarionType`	`string` or `string[]`	See application	Maps this entity to one or more Polarion work item type IDs. Accepts a single string or a list for multi-type entities.
`polarionProto`	`string`	`IWorkItem.PROTO`	Specifies the Polarion prototype (object type) this entity maps to. Determines which Polarion object class this entity can represent.
`properties`	`map`	`{}`	Map of property definitions that define the fields available on this entity type. See Properties.
`constraints`	`object`	None	Optional data scoping rules. See Constraints.

Entity type names must be single words without spaces or special characters. Relationship from and to fields reference these entity type names — not Polarion work item type IDs. Using an invalid name causes configuration errors.

PascalCase (e.g., UserNeed, SystemRequirement) is a common convention for entity type names, but it is not a requirement. Names are case-sensitive.

`name`

The entity type name is the primary identifier used throughout the data model. It is set automatically from the YAML map key and does not need to be specified separately.

domainModelTypes:
  UserNeed:           # name = "UserNeed"
    polarionType: user_need
  SystemRequirement:  # name = "SystemRequirement"
    polarionType: sys_req

Entity type names are used in:

relationships[].from and relationships[].to to reference participating types
Sheet source query.from to identify the root entity type
Expansion paths to navigate between related entities
Metadata system queries for type-based filtering

`pluralName`

An optional plural form of the entity type name. When omitted, Powersheet auto-generates it using standard English pluralization rules.

domainModelTypes:
  Hazard:
    polarionType: hazard
    pluralName: Hazards

The pluralName property has limited support in current versions. Auto-generated pluralization covers most standard English forms.

`polarionType`

Maps the data model entity to one or more Polarion work item types. This property is critical for Powersheet’s integration with Polarion — it determines which work items this entity type can represent. Single type mapping:

SystemRequirement:
  polarionType: sys_req

Multiple type mapping:

Requirement:
  polarionType:
    - sys_req
    - des_req

When multiple types are specified, the entity type matches work items of any of the listed Polarion types. This enables a single entity type to aggregate work items across multiple Polarion types. See Polarion Type Mapping for details on type resolution.

`polarionProto`

Specifies the Polarion prototype (object type) this entity maps to. Most entity types use the default work item prototype and do not need to set this property.

Value	Usage
`IWorkItem.PROTO` (default)	Standard work items
Other prototypes	Non-work-item Polarion objects

Document:
  polarionProto: IModule.PROTO

`properties`

Defines which fields are available on this entity type. Properties are declared as a map where the key is the property name.

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

An empty value after the property name declares the property with all default settings. To customize a property, provide a configuration object:

UserNeed:
  properties:
    title:
      readable: true
      updatable: true
    outlineNumber:
      readable: true
      updatable: false
    renderColumn:
      serverName: customRenderField

Properties must be declared as a YAML map. Array format (using - name: syntax) is not supported.

Properties can represent:

Polarion built-in fields — standard work item fields like title, description, severity
Custom fields — Polarion custom fields identified by customFieldName
Virtual properties — properties not backed by any Polarion field, commonly used as targets for server rendering or computed display columns

For detailed property configuration including serverName, customFieldName, type, storage, scalar, and navigability, see Properties.

Built-in Properties

All entity types automatically include these properties without explicit declaration:

Property	Type	Description
`objectId`	`string`	Unique entity identifier (primary key)
`id`	`string`	Polarion work item ID
`title`	`string`	Work item title
`projectId`	`string`	Polarion project identifier (foreign key)

Permission Flags on Properties

Individual properties support field-level access control:

Flag	Type	Default	Description
`readable`	`boolean`	`true`	Whether the property is visible to users in the sheet and available in queries
`updatable`	`boolean`	`true`	Whether the property can be modified through save operations

SystemRequirement:
  properties:
    description:
      readable: true
      updatable: true
    outlineNumber:
      readable: true
      updatable: false
    internalStatus:
      readable: false
      updatable: false

Setting readable: false hides the property entirely from the metadata system. Setting updatable: false makes the property read-only in the sheet while still allowing it to be displayed. See Permissions for additional access control options.

`constraints`

Defines data scoping rules at three lifecycle points. Constraints control which work items are loaded, which can be selected in pickers, and how new entities are created. See Constraints for full reference.

SystemRequirement:
  polarionType: sys_req
  constraints:
    load:
      document:
        type: systemSpecification
    create:
      document:
        moduleFolder: Requirements
        moduleName: System Specification
    pick:
      document:
        type: systemSpecification

Constraint	Purpose
`load`	Filters which entities are fetched during initial data loading. Applies a Lucene query scope.
`create`	Configures defaults for newly created entities: document location, project routing, default field values, and type/relation constraints.
`pick`	Restricts which entities appear in picker dialogs when creating or editing relationships.

The load constraint affects what data is visible in the sheet. The pick constraint independently controls what items appear in reference pickers. The create constraint controls the full creation workflow including where new items are placed and what defaults they receive.

Built-in Entity Types

Powersheet provides the Document entity type without explicit declaration. All other entity types, including Chapter, must be declared in the domainModelTypes map.

Entity Type	Requires Declaration	Description
`Document`	No	Represents Polarion documents (LiveDoc modules). Exposes module properties like `moduleName`, `title`, `titleOrName`, `titleWithSpace`, and `allowedWITypes`. Not a work item type.
`Project`	No	Represents the Polarion project. Linked to all work item entities via `projectObjectId`.
`Chapter`	Yes	Represents heading work items in document structures. Must be explicitly declared with `polarionType: heading`.

The Document entity type is not a work item. It provides navigation access to the containing document’s properties for filtering and constraints. It uses a different Polarion prototype than standard entity types.

Declaring Chapter

To use Chapter in your data model, declare it explicitly:

domainModelTypes:
  Chapter:
    polarionType: heading

Chapters are commonly used in many-to-one relationships where work items belong to a document section:

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

How Entity Types Connect to Sources and Columns

Entity types defined in domainModelTypes are referenced throughout the sheet configuration. The connection flows through three layers:

Data model — defines entity types and their relationships
Sheet sources — queries entity types and expands relationships
Sheet columns — binds to entity properties using dot-notation paths

The cardinality of a relationship determines the expand pattern and column binding syntax.

Cardinality Summary

Cardinality	Source Expand	Column Binding	UI Behavior
N:1 (many-to-one)	`- name: chapter`	`chapter`, `chapter.title`	Single-value reference picker
1:N (one-to-many)	`- name: userNeeds`	`userNeeds`	Child rows (new sheet level)
M:N (many-to-many)	`- name: systemRequirements` then `- name: systemRequirement`	`systemRequirements.systemRequirement`	Multi-item reference picker

See Relationships for relationship configuration and Binding Syntax for column path resolution.

Complete YAML Example

A comprehensive data model using the standard RTM entity set:

domainModelTypes:
  Chapter:
    polarionType: heading

  UserNeed:
    polarionType: user_need
    properties:
      description:
      severity:

  SystemRequirement:
    polarionType: sys_req
    properties:
      description:
      severity:
      component:
      type:
    constraints:
      load:
        document:
          type: systemSpecification
      create:
        document:
          moduleFolder: Requirements
          moduleName: System Specification
      pick:
        document:
          type: systemSpecification

  DesignRequirement:
    polarionType: des_req
    properties:
      description:
      severity:
    constraints:
      create:
        document:
          moduleFolder: Design
          moduleName: Design Specification

  Hazard:
    polarionType: hazard
    properties:
      description:
      severity:

  RiskControl:
    polarionType: riskControl
    properties:
      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

  - from: SystemRequirement
    to: DesignRequirement
    cardinality: one-to-many
    storage: linkedWorkItems
    linkRole: refines
    direct:
      name: designRequirements
    back:
      name: systemRequirement

  - from: Hazard
    to: RiskControl
    cardinality: many-to-many
    storage: linkedWorkItems
    linkRole: mitigates
    direct:
      name: riskControls
    back:
      name: hazards

Programmatic Access

Powersheet provides several methods for accessing entity type definitions at runtime:

Method	Return Type	Description
`getDomainModelTypes()`	Collection	Returns all entity type definitions. Ensures type names are mapped before returning.
`getDomainModelTypesMap()`	Map	Returns entity types keyed by name for lookup access.
`getDomainModelType(name)`	Optional	Retrieves a specific entity type by name. Returns empty if the type does not exist.
`getProperty(name)`	Property	Retrieves a specific property definition from an entity type. Returns null if the property does not exist.
`addProperty(name, property)`	void	Programmatically adds a property definition to an entity type. Validates that the property name is not null or empty.

Programmatic access is primarily used in server-side extensions and custom Velocity templates. Standard sheet configuration uses the YAML declaration approach.

Relationships — Relationship definitions between entity types
Properties — Property configuration details including serverName, customFieldName, and type
Constraints — Load, create, and pick constraint reference
Cardinality — How relationship cardinality affects sources and columns
Polarion Type Mapping — How polarionType resolves to work item types
Permissions — Property-level access control
Link Roles — Polarion link role configuration for relationships
Navigation Directions — Forward and reverse navigation properties

​Top-Level Structure

​Entity Type Diagram

​Entity Type Configuration Properties

​name

​pluralName

​polarionType

​polarionProto

​properties

​Built-in Properties

​Permission Flags on Properties

​constraints

​Built-in Entity Types

​Declaring Chapter

​How Entity Types Connect to Sources and Columns

​Cardinality Summary

​Complete YAML Example

​Programmatic Access

​Related Pages

Top-Level Structure

Entity Type Diagram

Entity Type Configuration Properties

`name`

`pluralName`

`polarionType`

`polarionProto`

`properties`

Built-in Properties

Permission Flags on Properties

`constraints`

Built-in Entity Types

Declaring Chapter

How Entity Types Connect to Sources and Columns

Cardinality Summary

Complete YAML Example

Programmatic Access

Related Pages