> For the complete documentation index, see [llms.txt](https://docs.umh.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.umh.app/reference/data-model-type-definitions.md).

# Data Model Type Definitions

> This is a reference document. Use it to look up the types that a data model field accepts and the errors the validator may raise.

A field's value type is declared at one of two levels. A data model field references a type with `_payloadshape` (a named payload shape) or `_refModel` (another data model). Inside a payload shape, each field declares a scalar directly with `_type`.

## Field Types (`_type`)

A [payload shape](https://github.com/united-manufacturing-hub/united-manufacturing-hub/tree/staging/umh-core/docs/reference/payload-shapes.md) field's `_type` is one of:

| `_type`   | Meaning                             | Example value |
| --------- | ----------------------------------- | ------------- |
| `string`  | Text                                | `"running"`   |
| `number`  | Any numeric value, decimal or whole | `42.5`, `42`  |
| `boolean` | True / false                        | `true`        |

Any other value is rejected: `unsupported UMH type: <type>`.

## Timeseries payload shapes are inherently typed

When defining the `_payloadshape` to be timeseries data, the name of the payload shape already states the type. As such, no additional type definition is needed.

| Payload shape        | `value` type | Use for                         |
| -------------------- | ------------ | ------------------------------- |
| `timeseries-number`  | `number`     | Numeric readings (temperature…) |
| `timeseries-string`  | `string`     | Text status values              |
| `timeseries-boolean` | `boolean`    | On/off, true/false state        |

Each built-in timeseries shape also carries `timestamp_ms` (a `number`) next to `value`. Both fields come from the built-in shape definition, so you never declare `timestamp_ms` yourself. See [Built-in Shapes](https://github.com/united-manufacturing-hub/united-manufacturing-hub/tree/staging/umh-core/docs/reference/payload-shapes.md#built-in-shapes) for the full payload structure.

A `_payloadshape` reference must name one of the three built-ins above or a shape defined under `payloadShapes:`. Any other name fails validation with `referenced payload shape '<name>' does not exist`.

```yaml
temperature:
  _payloadshape: timeseries-number
status:
  _payloadshape: timeseries-string
```

## Examples

Data model with several timeseries fields:

```yaml
dataModels:
  - name: temperature
    version:
      v1:
        structure:
          temperature:
            _payloadshape: timeseries-number
          unit:
            _payloadshape: timeseries-string
```

Nested folders, and a field that references another data model (`_refModel`):

```yaml
dataModels:
  - name: complex-model
    version:
      v1:
        structure:
          sensor: # folder here
            temp_reading:
              _payloadshape: timeseries-number
            temp_unit:
              _refModel:
                name: temperature
                version: v1
          metadata:
            _refModel:
              name: device-info
              version: v1
```

Multiple versions of one model:

```yaml
dataModels:
  - name: sensor-data
    version:
      v1:
        structure:
          value:
            _payloadshape: timeseries-number
      v2:
        structure:
          value:
            _payloadshape: timeseries-number
          status:
            _payloadshape: timeseries-string
```

Define a custom [payload shape](https://github.com/united-manufacturing-hub/united-manufacturing-hub/tree/staging/umh-core/docs/reference/payload-shapes.md) (top-level `payloadShapes:`), then reference it:

```yaml
payloadShapes:
  work-order:
    description: Work order record
    fields:
      orderId:
        _type: string
      quantity:
        _type: number
      price:
        _type: number
      active:
        _type: boolean

dataModels:
  - name: orders
    version:
      v1:
        structure:
          order:
            _payloadshape: work-order
```

Rules a data model field must follow:

* A leaf field references its type with `_payloadshape` or `_refModel`, never both.
* A folder (a field with subfields) has neither `_payloadshape` nor `_refModel`.

## Validation Errors

| Error message                                                      | Cause                                                              | Fix                                                             |
| ------------------------------------------------------------------ | ------------------------------------------------------------------ | --------------------------------------------------------------- |
| `referenced payload shape '<name>' does not exist`                 | `_payloadshape` names a shape that is not built-in and not defined | Use a built-in, or define the shape first                       |
| `unsupported UMH type: <type>`                                     | A field `_type` is not a supported type                            | Use `string`, `number`, or `boolean`                            |
| `field cannot have both _payloadshape and _refModel`               | A leaf field sets both keys                                        | Keep one                                                        |
| `leaf nodes must contain _payloadshape, _relational, or _refModel` | A leaf field has no value-type key                                 | Add `_payloadshape` or `_refModel`, or give the field subfields |
| `non-leaf nodes (folders) cannot have _payloadshape`               | A field with subfields also sets `_payloadshape`                   | Remove `_payloadshape` from the folder                          |

## Related

* [Data Modeling](/reference.md) - Concepts and the component chain
* [Payload Shapes](https://github.com/united-manufacturing-hub/united-manufacturing-hub/tree/staging/umh-core/docs/reference/payload-shapes.md) - Built-in and custom shapes
* [Data Models](https://github.com/united-manufacturing-hub/united-manufacturing-hub/tree/staging/umh-core/docs/reference/data-models.md) - Structure, `_refModel`, versions
* [Data Contracts](https://github.com/united-manufacturing-hub/united-manufacturing-hub/tree/staging/umh-core/docs/reference/data-contracts.md) - Enforcement at ingress
* [Payload Formats](https://github.com/united-manufacturing-hub/united-manufacturing-hub/tree/staging/umh-core/docs/unified-namespace/payload-formats.md) - UNS payload structure

> ### Note: the `integer` type
>
> The YAML validator also accepts `_type: integer` inside a custom payload shape defined in an instance's config file. However, there is no built-in `timeseries-integer` shape and the data-model editor does not offer it, so most models never need it. Use `number` for numeric values. `integer` is only relevant when a custom payload shape must reject fractional values (for example a discrete count or an ID).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.umh.app/reference/data-model-type-definitions.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.