Data Models

This article assumes you've completed the Getting Started guide and understand the data modeling concepts.

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

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

Configuration

Basic Structure

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:

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

temperature:
  _payloadshape: timeseries-number  # Accepts numeric values

Characteristics:

• Has _payloadshape property

• Creates a topic endpoint that accepts data

• References a payload shape for validation

• Cannot have child elements

Folders

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:

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

• Models are contracts between teams

• Dashboards depend on stable structure

• Historical data queries must not break

Evolution Pattern

Version 1 - Basic:

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

Version 2 - Add pressure:

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 come in:

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 - Make models mandatory

• Payload Shapes - Specify data types for fields

• Stream Processors - Transform device models to business models