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

# Data Model Types

> The `domainModelTypes` section is the primary configuration block in the Nextedy POWERSHEET data model YAML.

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>;
};

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

```yaml theme={null}
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.

<Warning title="Map format only">
  `domainModelTypes` must be a YAML map. Array format is **not** supported.
</Warning>

## Entity Type Diagram

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

## 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](/powersheet/guides/data-model/create-entity-type). |
| `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](/powersheet/reference/data-model/properties).                            |
| `constraints`   | `object`               | None                       | Optional data scoping rules. See [Constraints](/powersheet/reference/data-model/constraints).                                                                               |

<Warning title="Naming rules">
  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.
</Warning>

<Tip title="Naming convention">
  PascalCase (e.g., `UserNeed`, `SystemRequirement`) is a common convention for entity type names, but it is not a requirement. Names are case-sensitive.
</Tip>

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

```yaml theme={null}
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.

```yaml theme={null}
domainModelTypes:
  Hazard:
    polarionType: hazard
    pluralName: Hazards
```

<Info title="Verify in application">
  The `pluralName` property has limited support in current versions. Auto-generated pluralization covers most standard English forms.
</Info>

## `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:**

```yaml theme={null}
SystemRequirement:
  polarionType: sys_req
```

**Multiple type mapping:**

```yaml theme={null}
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](/powersheet/reference/data-model/polarion-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 |

```yaml theme={null}
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.

```yaml theme={null}
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:

```yaml theme={null}
UserNeed:
  properties:
    title:
      readable: true
      updatable: true
    outlineNumber:
      readable: true
      updatable: false
    renderColumn:
      serverName: customRenderField
```

<Warning title="Map format only">
  Properties must be declared as a YAML map. Array format (using `- name:` syntax) is **not** supported.
</Warning>

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](/powersheet/reference/server-rendering/velocity-templates) or computed display columns

For detailed property configuration including `serverName`, `customFieldName`, `type`, `storage`, `scalar`, and `navigability`, see [Properties](/powersheet/reference/data-model/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                   |

```yaml theme={null}
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](/powersheet/reference/data-model/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](/powersheet/reference/data-model/constraints) for full reference.

```yaml theme={null}
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.                                                |

<Tip title="Constraint interaction">
  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.
</Tip>

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

<Note title="Document entity">
  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.
</Note>

### Declaring Chapter

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

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

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

```yaml theme={null}
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:

1. **Data model** -- defines entity types and their relationships
2. **Sheet sources** -- queries entity types and expands relationships
3. **Sheet columns** -- binds to entity properties using dot-notation paths

The [cardinality](/powersheet/reference/data-model/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](/powersheet/reference/data-model/relationships) for relationship configuration and [Binding Syntax](/powersheet/reference/sheet-config/binding-syntax) for column path resolution.

## Complete YAML Example

A comprehensive data model using the standard RTM entity set:

```yaml theme={null}
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. |

<Info title="Verify in application">
  Programmatic access is primarily used in server-side extensions and custom Velocity templates. Standard sheet configuration uses the YAML declaration approach.
</Info>

## Related Pages

* [Relationships](/powersheet/reference/data-model/relationships) -- Relationship definitions between entity types
* [Properties](/powersheet/reference/data-model/properties) -- Property configuration details including `serverName`, `customFieldName`, and `type`
* [Constraints](/powersheet/reference/data-model/constraints) -- Load, create, and pick constraint reference
* [Cardinality](/powersheet/reference/data-model/cardinality) -- How relationship cardinality affects sources and columns
* [Polarion Type Mapping](/powersheet/reference/data-model/polarion-mapping) -- How `polarionType` resolves to work item types
* [Permissions](/powersheet/reference/data-model/permissions) -- Property-level access control
* [Link Roles](/powersheet/reference/data-model/link-roles) -- Polarion link role configuration for relationships
* [Navigation Directions](/powersheet/reference/data-model/navigation-directions) -- Forward and reverse navigation properties

***

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