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": [...]
}

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'.

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