# Data Models

> This article assumes you've completed the [Getting Started guide](https://docs.umh.app/getting-started) and understand the [data modeling concepts](https://docs.umh.app/usage/data-modeling).

Data models define the hierarchical structure of your industrial data. They create the virtual paths and fields that organize raw data into meaningful information.

## Overview

In the [component chain](https://docs.umh.app/usage/data-modeling/..#the-component-chain), models provide the structure:

```
Payload Shapes → Data Models → Data Contracts → Data Flows
                      ↑
                 Structure defined here
```

When you create a data model, you're defining:

* Virtual paths - organizational folders (e.g., `vibration`, `motor.electrical`)
* Fields - data endpoints with specific types (e.g., `temperature`, `pressure`)
* Relationships - how components nest and reference each other

## UI Capabilities

The Management Console provides full control over data models:

| Feature              | Available | Notes                                    |
| -------------------- | --------- | ---------------------------------------- |
| View model list      | ✅         | Shows all models with versions           |
| Create models        | ✅         | Visual editor with YAML preview          |
| View model details   | ✅         | Inspect structure and configuration      |
| Create new versions  | ✅         | Models are immutable, edit by versioning |
| Reference sub-models | ✅         | Link to other models via `_refModel`     |
| Delete models        | ✅         | Remove unused model versions             |
| Direct editing       | ❌         | Use "New Version" to modify              |

![Data Models List](https://3966587046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FPQ7UY9eT1SiICDqYFZdA%2Fuploads%2Fgit-blob-ed7eb5308527c12f86b88c7bf64d7dbde1d50b85%2Fdata-models.png?alt=media)

**What you see in the UI:**

* **Name**: Model identifier (e.g., `cnc`, `pump`, `temperature-sensor`)
* **Instance**: Which UMH Core instance owns the model
* **Description**: Optional description of the model's purpose
* **Latest**: Current version number (v1, v2, etc.)

### Model Actions

Click the three-dot menu (⋮) on any model to access actions:

![Data Model Actions](https://3966587046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FPQ7UY9eT1SiICDqYFZdA%2Fuploads%2Fgit-blob-933de38bf55804d55d53cbd890f0dd8ff0de458a%2Fdata-models-context-menu.png?alt=media)

* **Data Model**: View the model's structure and YAML configuration
* **New Version**: Create a new version with modifications (since models are immutable)
* **Delete**: Remove the model (only if not in use by contracts or bridges)

![Data Model Creation](https://3966587046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FPQ7UY9eT1SiICDqYFZdA%2Fuploads%2Fgit-blob-572bd67a6437713948a8d4ce2b20888e218d8d80%2Fdata-models-add.png?alt=media)

## Configuration

### Basic Structure

```yaml
datamodels:
  - name: pump                    # Model name
    description: "Pump monitoring" # Optional description
    version:
      v1:                         # Version identifier
        structure:                # Hierarchical definition
          pressure:
            inlet:
              _payloadshape: timeseries-number
            outlet:
              _payloadshape: timeseries-number
```

### How Structure Becomes Topics

Model structure directly maps to UNS topics:

```yaml
structure:
  vibration:        # Creates: .../_pump_v1.vibration
    x-axis:         # Creates: .../_pump_v1.vibration.x-axis
```

**Complete topic path:**

```
umh.v1.enterprise.site._pump_v1.vibration.x-axis
       └─ fixed ─┘     └contract┘└─from model─┘
```

## The Three Building Blocks

### Fields

```yaml
temperature:
  _payloadshape: timeseries-number  # Accepts numeric values
```

**Characteristics:**

* Has `_payloadshape` property
* Creates a topic endpoint that accepts data
* References a [payload shape](https://docs.umh.app/usage/data-modeling/payload-shapes) for validation
* Cannot have child elements

### Folders

```yaml
vibration:           # Folder - no _payloadshape
  x-axis:           # Field inside folder
    _payloadshape: timeseries-number
  y-axis:           # Field inside folder
    _payloadshape: timeseries-number
```

**Characteristics:**

* No `_payloadshape` property
* Groups related fields or other folders
* Creates hierarchy in topic path
* Can nest multiple levels deep

### Sub-Models

Define once, use everywhere:

```yaml
# Define reusable motor model
datamodels:
  - name: motor
    version:
      v1:
        structure:
          rpm:
            _payloadshape: timeseries-number
          temperature:
            _payloadshape: timeseries-number

# Reference in pump model
datamodels:
  - name: pump
    version:
      v1:
        structure:
          pressure:
            inlet:
              _payloadshape: timeseries-number
          motor:           # Include the motor model
            _refModel:
              name: motor
              version: v1
```

Topics created:

* `_pump_v1.pressure.inlet`
* `_pump_v1.motor.rpm`
* `_pump_v1.motor.temperature`

**Benefits:**

* Single source of truth
* Consistent structure across models
* Update once, reflected everywhere

## Version Evolution

Models are immutable once created. To add fields, create a new version:

### Why Immutability?

From the [README](https://docs.umh.app/usage/data-modeling/..#why-are-models-immutable):

* Models are contracts between teams
* Dashboards depend on stable structure
* Historical data queries must not break

### Evolution Pattern

**Version 1 - Basic:**

```yaml
version:
  v1:
    structure:
      temperature:
        _payloadshape: timeseries-number
```

**Version 2 - Add pressure:**

```yaml
version:
  v2:
    structure:
      temperature:
        _payloadshape: timeseries-number
      pressure:                          # New field
        _payloadshape: timeseries-number
```

**Migration steps:**

1. Create v2 with additions
2. Deploy new bridges using v2
3. Update dashboards to v2
4. Keep v1 running during transition
5. Deprecate v1 when safe

## Relationship to Contracts

Models define structure, but don't enforce it. That's where [data contracts](https://docs.umh.app/usage/data-modeling/data-contracts) come in:

| Component    | Purpose            | Example                       |
| ------------ | ------------------ | ----------------------------- |
| **Model**    | Defines structure  | `pump` model with fields      |
| **Contract** | Enforces structure | `_pump_v1` validates messages |

When you create a model in the UI:

1. Model `pump` version `v1` is created
2. Contract `_pump_v1` is auto-generated
3. Contract becomes available in bridges

Without a contract, a model is just documentation. With a contract, it becomes validation.

## Next Steps

* [Data Contracts](https://docs.umh.app/usage/data-modeling/data-contracts) - Make models mandatory
* [Payload Shapes](https://docs.umh.app/usage/data-modeling/payload-shapes) - Specify data types for fields
* [Stream Processors](https://docs.umh.app/usage/data-modeling/stream-processors) - Transform device models to business models