Payload Shapes

Payload shapes define reusable JSON schemas for field values in industrial data models.

Payload shapes define the JSON schema for field values. They provide reusable templates for common data structures in industrial systems, ensuring consistency across your data models.

Overview

Payload shapes are stored in the payloadshapes: configuration section and define the structure of data that flows through your UNS topics. They use _type: to define the types of fields within the payload shape structure:

payloadshapes:
  timeseries-number:
    fields:
      timestamp_ms:
        _type: number
      value:
        _type: number
  timeseries-string:
    fields:
      timestamp_ms:
        _type: number
      value:
        _type: string

Built-in Payload Shapes

Timeseries Number

The default payload shape for numeric sensor data:

payloadshapes:
  timeseries-number:
    fields:
      timestamp_ms:
        _type: number
      value:
        _type: number

Example payload:

{
  "value": 42.5,
  "timestamp_ms": 1733904005123
}

Common use cases:

• Temperature measurements

• Pressure readings

• RPM values

• Current measurements

• Power consumption

Timeseries String

For textual sensor data and status values:

payloadshapes:
  timeseries-string:
    fields:
      timestamp_ms:
        _type: number
      value:
        _type: string

Example payload:

{
  "value": "running",
  "timestamp_ms": 1733904005123
}

Common use cases:

• Equipment status ("running", "stopped", "fault")

• Serial numbers

• Product codes

• Error messages

• Operator notes

Usage in Data Models

Payload shapes are referenced in data models using the _payloadshape: property:

datamodels:
  pump:
    description: "Pump with various measurements"
    versions:
      v1:
        structure:
          pressure:
            _payloadshape: timeseries-number
          status:
            _payloadshape: timeseries-string

Type System

The _type: field (used within payload shapes) can reference:

Basic Types

• number: Numeric values (integers, floats)

• string: Text values

• boolean: True/false values

Relational Payload Shapes

🚧 Roadmap Item - Relational payload shapes for complex relational data:

payloadshapes:
  relational-meldePerson:
    fields:
      perso_no:
        _type: string
      gesundheit:
        pulse:
          value:
            _type: number
          messaured_at:
            _type: number
  relational-setzeStatus:
    fields:
      status:
        _type: string
      timestamp:
        _type: number
  relational-aendereStatus:
    fields:
      old_status:
        _type: string
      new_status:
        _type: string
      changed_at:
        _type: number

Best Practices

Naming Convention

• Use hyphenated names: timeseries-number, batch-report

• Include data type: timeseries-number vs. just timeseries

Design Principles

• Keep shapes focused: Each shape should serve a specific purpose

• Favor composition: Use existing shapes as building blocks

• Plan for evolution: Consider future field additions

• Document use cases: Clear examples of when to use each shape

Field Organization

• Group related fields: Logical field grouping within shapes

• Use consistent naming: timestamp_ms not time or ts

• Include required metadata: Timestamp fields for time-series data

Related Documentation

• Data Models - Using payload shapes in data models

• Data Contracts - Storage and retention policies

• Stream Processors - Processing data with payload shapes

• Payload Formats - UNS payload structure