Generic Data Model Extensions¶

Introduction¶

This document outlines the well-known properties and schema extensions for the Generic Data Model (GDM) schema. By utilizing these extension properties, you can incorporate additional information into your GDM messages, which in turn, offers more context and insights for the ingested data. Buhler Insights leverages these extensions to deliver enhanced functionality.

Well-known message-level metadata¶

Message metadata location¶

{
    "deviceId": "Fast_Baker_42",
    "messageId": "d32779a6-9b8e-4fa0-9941-9a147040f24a",
    "messageType": "state",
    "messageVersion": "1.0",
    "metadata": {
        "jobStart": "2022-09-23T14:30:59.1234567Z" // Message metadata property
    },
    "data": [...]
}

Well known custom message types¶

In addition to the standard message types defined in the GDM specification, the following custom message types are recognized:

Message Type	CustomType	Description
event	asset-health-event	Used to report the current health status of a machine or component.

Message metadata properties¶

The following table lists the well-known message metadata properties that can be used in GDM messages.

Property	Type	Access Scope	Description
topologyReference	String	Public	Used to reference a topology element, e.g. a machine number.
topologyReferenceType	String	Public	Defines the TopologyReference "type", e.g. topology-machine-machineNumber.
messageIntervalMilliseconds	Integer	Public	Expected interval in milliseconds of the message type. This information is used to setup message tracking.
plantId	String	Internal	The plant identifier.
tenantId	String	Internal	The tenant identifier.
timeZoneId	String	Internal	IANA Time Zone Database identifier.
correlationId	String	Internal	Large messages are split and related using this GUID property.
jobStartTime	String	Internal	The start time of the job.
jobEndTime	String	Internal	The end time of the job.
jobId	String	Internal	The job identifier.
jobName	String	Internal	The name of the job.
recipeName	String	Internal	The name of the recipe.
dataTransmissionType	String	Internal	Specifies if the data points in the message are 'delta' or a 'keyFrame' items.

Important

Internal properties must not be set by the producer. Those will be set by the ingestion process.

Well-known data metadata¶

Data metadata location¶

{
    "deviceId": "Fast_Baker_42",
    "messageId": "d32779a6-9b8e-4fa0-9941-9a147040f24a",
    "messageType": "state",
    "messageVersion": "1.0",
    "data": [
        {
            "name": "Temperature_Heater",
            "metadata": {
                "unit": "C",
                "datapointSourceId": "oven1" // Data metadata property
            },
            "values": [
                {
                    "deviceTimestamp": "2020-01-16T09:30:02.500Z",
                    "value": 120.3
                },
                {
                    "deviceTimestamp": "2020-01-16T09:31:09.000+01:00",
                    "value": 139.8
                }
            ]
        },
        {
            "name": "Temperature_Heater",
            "metadata": {
                "unit": "C",
                "datapointSourceId": "oven2" // Data metadata property
            },
            "values": [
                {
                    "deviceTimestamp": "2020-01-16T09:30:02.500Z",
                    "value": 120.3
                },
                {
                    "deviceTimestamp": "2020-01-16T09:31:09.000+01:00",
                    "value": 139.8
                }
            ]
        }
    ]
}

Data metadata properties¶

The following table lists the well-known message metadata properties that can be used in GDM messages.

Property	Type	Access Scope	Description
datapointSourceId	String	Public	Used to reference a data source, e.g. a room number and distinguish data points with the same names, e.g. temperature.
datapointAddress	String	Public	The exact address of the data source e.g. OPC UA node id.
logicalPath	String	Public	Hierarchical path to the data source e.g. roll1::left::temperature.
logicalName	String	Public	Logical name of the data source e.g. Top roll, left sensor.
conditionId	String	Public	Used to correlate job events e.g. Die Casting start/stop events.
conditionName	String	Internal	The name of an opc ua condition
sourceName	String	Internal	The source of an opc ua condition
topologyReference	String	Public	Used to reference a topology element, e.g. a machine number.
topologyReferenceType	String	Public	Defines the TopologyReference "type", e.g. topology-machine-machineNumber.
active	Boolean	Public	Used to indicate if an alarm is active or not.
severity	String	Public	Used to indicate the severity of an alarm.
reason	String	Public	Used to indicate the reason of an alarm.
state	String	Public	Used to indicate the state of an alarm.
text	String	Public	The text description of an alarm.
jobStartTime	String	Internal	The start time of the job.
jobEndTime	String	Internal	The end time of the job.
jobId	String	Internal	The job identifier.
jobName	String	Internal	The name of the job.
recipeName	String	Internal	The name of the recipe.
dataTransmissionType	String	Internal	Specifies if the data point is a 'delta' or a 'keyFrame'.
eventId	String	Internal	ID coming from producer, should Uniquely identify the event.
diagnosisCode	String	Internal	Acts as identifier of the diagnosed issue.

Health Event¶

A health event message is a special kind of event with a fixed custom message type (event:asset-health-event_v1.0). This message type allows the system to reliably determine the health state of a machine or component. Health events are utilized by Condition Based Maintenance (CBM) systems to trigger maintenance actions, generate work orders, and monitor asset health over time. The message structure includes well-known metadata fields and custom properties that provide context about the event, its origin, and the diagnosed issue.

Metadata Properties¶

Key	Type	Description
topologyReference	String	References the topology element (e.g., machine number) associated with the health event.
topologyReferenceType	String	Defines the type of topology reference (e.g., topology-machine-machineNumber).
eventId	String	Uniquely identifies the health event instance; typically set by the rule engine.
conditionId	String	Identifies the reason or rule for raising the health event (e.g., RuleId from Rule Service).
diagnosisCode	String	Identifier for the diagnosed issue (e.g., RING_WEIGHT_LOW).
text	String	Descriptive text about the health event;
severity	String	Severity of the health event; possible values: "Info", "Warning", "Error".

Sample message¶

{
  "deviceId":       "rule-service", // well known virtual device for Rule service
  "messageId":      "d32779a6-9b8e-4fa0-9941-9a147040f24a",
  "messageType":    "event:asset-health-event_v1.0", // well known custom message type for health event 
  "messageVersion": "1.0",
  "metadata": { "plantId": "123123" },// Will be added implicitely, producer will not care about it
  "data": [
    {
      "name": "RING_WEIGHT_HEALTH", // It can be same as Machine/Component Health
      /* ←––––– CUSTOM FIELDS live here ––––––→ */
      "metadata": {
        "topologyReference":  "000012341234",
        "topologyReferenceType": "topology-machine-machineNumber",

        /* The two IDs that form the HA → AG contract */ Well Known
        "eventId": "he-20251016-0901", // ID coming from Rule Engine or any producer, and should Uniquely identify the event, may be another GUID ,mandatory for health event

         // For Rule Service it should be the RuleId, and nothing to do with the conditionId of the Rule service          
        "conditionId" : "b32779a6-9b8e-4fa0-9941-9a147040f28a"    //   inspired by OPC-UA structure 

        "diagnosisCode": "RING_WEIGHT_LOW", // acts as identifier of the diagnosed issue.
        "text": "The value OurRingWeight Level was lower than 25. Actual value was 18." // Additional information about conditions . // 200 char in UTF-8 will be taken for creation of workorder request. Producer application should strip at 197 character and add ellipses (...)
        "severity" : "error" // Possible values  "Info","Warning", "Error" // default is error, but user can override, and it should co-relate the value specified

      },

      "values": [
        {
          "deviceTimestamp": "2025-10-16T06:32:54.500Z",
          "value": 0.1 /* 
            0 - 1, 0 for unhealthy and 1 for healthy where values in between would be possible in the future.
            */
        }
      ]
    }    
  ]
}

{"environments":[],"pdf-download":true}