From cb02256ec1f27bc3f46339e4b7ce645c08060b58 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alexander=20K=C3=B6pke?= Date: Tue, 26 Mar 2024 11:32:04 +0000 Subject: [PATCH 01/14] Initial version for OPC UA extension MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Alexander Köpke --- cloudevents/extensions/README.md | 1 + cloudevents/extensions/opcua.md | 91 ++++++++++++++++++++++++++++++++ 2 files changed, 92 insertions(+) create mode 100644 cloudevents/extensions/opcua.md diff --git a/cloudevents/extensions/README.md b/cloudevents/extensions/README.md index e3c9bbcc9..4986b5fed 100644 --- a/cloudevents/extensions/README.md +++ b/cloudevents/extensions/README.md @@ -49,3 +49,4 @@ for more information. - [Sampling](sampledrate.md) - [Sequence](sequence.md) - [Severity](severity.md) +- [OPC UA](opcua.md) diff --git a/cloudevents/extensions/opcua.md b/cloudevents/extensions/opcua.md new file mode 100644 index 000000000..0f78608ae --- /dev/null +++ b/cloudevents/extensions/opcua.md @@ -0,0 +1,91 @@ +# OPC UA + +This extension defines the mapping of OPC UA DataSet to cloud events to allow seamless routing of OPC UA dataset messages via different protocols, it therefor provides an recommendation to map known mandatory and optional attributes using other extensions as well as defines own extended attributes. + +## Notational Conventions + +As with the main [CloudEvents specification](../spec.md), the key words "MUST", +"MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", +"RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as +described in [RFC 2119](https://tools.ietf.org/html/rfc2119). + +However, the scope of these key words is limited to when this extension is +used. For example, an attribute being marked as "REQUIRED" does not mean +it needs to be in all CloudEvents, rather it needs to be included only when +this extension is being used. + +## Mapping of REQUIRED Attributes + +### id + +MUST map to [Network Message Header](https://reference.opcfoundation.org/Core/Part14/v105/docs/7.2.5.3#Table163) field `MessageId`. + +### source + +MUST either map to [Application Description](https://reference.opcfoundation.org/Core/Part4/v104/docs/7.1) field `applicationUri` of the OPC UA server or to an customer configured Unified Namespace path. + +### type + +MUST map to [Network Message Header](https://reference.opcfoundation.org/Core/Part14/v105/docs/7.2.5.3#Table163) field `MessageType`. + +## Mapping of OPTIONAL Attributes + +### datacontenttype + +SHALL be `application/json` for OPC UA PubSub JSON payload and MAY be extended by `+gzip` when payload is gzip compressed. + +### dataschema + +OPC UA provides type information as part of PubSub metadata messages, for non OPC UA consumers or when different payload encodings like AVRO is used, it is required to provide schema information (based on metadata information) in a separate format like [JSON schema](https://json-schema.org/specification) or [AVRO schema](https://avro.apache.org/docs/1.11.1/specification/) or others. For those cases the Attribute references the schema and is used for versioning. + +### subject + +For metadata and data messages (type one of `ua-metadata`, `ua-keyframe`, `ua-deltaframe`) MUST map to either [Data Set Message Header](https://reference.opcfoundation.org/Core/Part14/v105/docs/7.2.5.4#Table164) field `DataSetWriterId` or `DataSetWriterName`. + +For event messages (type equals to `ua-event`) SHALL map to [Base Event Type](https://reference.opcfoundation.org/Core/Part5/v104/docs/6.4.2) field `EventId`. + +### time + +MUST map to [Data Set Message Header](https://reference.opcfoundation.org/Core/Part14/v105/docs/7.2.5.4#Table164) field `Timestamp`. + +## Mapping for other extensions + +The following extensions Attributes are REQUIRED for data messages and event messages (type one of `ua-keyframe`, `ua-deltaframe`, `ua-event`). + +### sequence + +Attribute as defined by [squence extensions](./sequence.md) MUST map to [Data Set Message Header](https://reference.opcfoundation.org/Core/Part14/v105/docs/7.2.5.4#Table164) field `SequenceNumber`. + +### traceparent + +Attribute as defined by [distributed-tracing extension](./distributed-tracing.md) SHALL be used to allow tracing from event publisher towards consumer. + +### tracestate + +Attribute as defined by [distributed-tracing extension](./distributed-tracing.md) might OPTIONAL be used to allow tracing from event publisher towards consumer. + +### recordedtime + +Attribute as defined by [recordedtime extension](./recordedtime.md) SHALL be used to determine the latency etween event publisher towards consumer. + +## Attributes + +### opcuametadataversion + +- Type: `String` +- Description: Links dataset message to the current version of the metadata. Contains JSON object of [Data Set Message Header](https://reference.opcfoundation.org/Core/Part14/v105/docs/7.2.5.4#Table164) field `MetaDataVersion`. +- Constraints + - OPTIONAL + - Can be omitted if `dataschema` is used + +### opcuastatus + +- Type: `Integer` +- Description: Defines the overall status of the data set message, maps to [Data Set Message Header](https://reference.opcfoundation.org/Core/Part14/v105/docs/7.2.5.4#Table164) field `Status`. +- Constraints + - OPTIONAL + - Can be omitted if status is _Good_ + +## General Constraints + +- OPC UA messages always use `binary-mode`. From 45f3be99241a40641f8ef50b6941142a41bc2e58 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alexander=20K=C3=B6pke?= Date: Tue, 26 Mar 2024 11:47:19 +0000 Subject: [PATCH 02/14] fixed type errors MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Alexander Köpke --- cloudevents/extensions/opcua.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/cloudevents/extensions/opcua.md b/cloudevents/extensions/opcua.md index 0f78608ae..8ebd94c46 100644 --- a/cloudevents/extensions/opcua.md +++ b/cloudevents/extensions/opcua.md @@ -1,6 +1,6 @@ # OPC UA -This extension defines the mapping of OPC UA DataSet to cloud events to allow seamless routing of OPC UA dataset messages via different protocols, it therefor provides an recommendation to map known mandatory and optional attributes using other extensions as well as defines own extended attributes. +This extension defines the mapping of OPC UA dataset to cloud events to allow seamless routing of OPC UA dataset messages via different protocols, it therefor provides an recommendation to map known mandatory and optional attributes using other extensions as well as defines own extended attributes. ## Notational Conventions @@ -22,7 +22,7 @@ MUST map to [Network Message Header](https://reference.opcfoundation.org/Core/Pa ### source -MUST either map to [Application Description](https://reference.opcfoundation.org/Core/Part4/v104/docs/7.1) field `applicationUri` of the OPC UA server or to an customer configured Unified Namespace path. +MUST either map to [Application Description](https://reference.opcfoundation.org/Core/Part4/v104/docs/7.1) field `applicationUri` of the OPC UA server or to an customer configured identifier like an unified namespace path. ### type @@ -36,7 +36,7 @@ SHALL be `application/json` for OPC UA PubSub JSON payload and MAY be extended b ### dataschema -OPC UA provides type information as part of PubSub metadata messages, for non OPC UA consumers or when different payload encodings like AVRO is used, it is required to provide schema information (based on metadata information) in a separate format like [JSON schema](https://json-schema.org/specification) or [AVRO schema](https://avro.apache.org/docs/1.11.1/specification/) or others. For those cases the Attribute references the schema and is used for versioning. +OPC UA provides type information as part of PubSub metadata messages, for non OPC UA consumers or when different payload encoding like Avro is used, it is required to provide schema information (based on metadata information) in a separate format like [JSON schema](https://json-schema.org/specification) or [Avro schema](https://avro.apache.org/docs/1.11.1/specification/) or others. For those cases the Attribute references the schema and is used for versioning. ### subject @@ -54,7 +54,7 @@ The following extensions Attributes are REQUIRED for data messages and event mes ### sequence -Attribute as defined by [squence extensions](./sequence.md) MUST map to [Data Set Message Header](https://reference.opcfoundation.org/Core/Part14/v105/docs/7.2.5.4#Table164) field `SequenceNumber`. +Attribute as defined by [sequence extensions](./sequence.md) MUST map to [Data Set Message Header](https://reference.opcfoundation.org/Core/Part14/v105/docs/7.2.5.4#Table164) field `SequenceNumber`. ### traceparent @@ -66,7 +66,7 @@ Attribute as defined by [distributed-tracing extension](./distributed-tracing.md ### recordedtime -Attribute as defined by [recordedtime extension](./recordedtime.md) SHALL be used to determine the latency etween event publisher towards consumer. +Attribute as defined by [recordedtime extension](./recordedtime.md) SHALL be used to determine the latency between event publisher towards consumer. ## Attributes From 54bf80dad61c88b8e123a5631b7560c129af9fff Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alexander=20K=C3=B6pke?= Date: Tue, 26 Mar 2024 14:55:23 +0000 Subject: [PATCH 03/14] split opcuametadataversion into separate attributes; added additional constraints MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Alexander Köpke --- cloudevents/extensions/opcua.md | 22 ++++++++++++++++------ 1 file changed, 16 insertions(+), 6 deletions(-) diff --git a/cloudevents/extensions/opcua.md b/cloudevents/extensions/opcua.md index 8ebd94c46..ebe55799e 100644 --- a/cloudevents/extensions/opcua.md +++ b/cloudevents/extensions/opcua.md @@ -32,7 +32,7 @@ MUST map to [Network Message Header](https://reference.opcfoundation.org/Core/Pa ### datacontenttype -SHALL be `application/json` for OPC UA PubSub JSON payload and MAY be extended by `+gzip` when payload is gzip compressed. +SHALL be `application/opcua+json` for OPC UA PubSub JSON payload and MAY be extended by `+gzip` when payload is gzip compressed. ### dataschema @@ -50,7 +50,7 @@ MUST map to [Data Set Message Header](https://reference.opcfoundation.org/Core/P ## Mapping for other extensions -The following extensions Attributes are REQUIRED for data messages and event messages (type one of `ua-keyframe`, `ua-deltaframe`, `ua-event`). +The following well-known extensions attributes are used for data messages and event messages (type one of `ua-keyframe`, `ua-deltaframe`, `ua-event`). ### sequence @@ -70,10 +70,18 @@ Attribute as defined by [recordedtime extension](./recordedtime.md) SHALL be use ## Attributes -### opcuametadataversion +### opcuametadatamajorversion -- Type: `String` -- Description: Links dataset message to the current version of the metadata. Contains JSON object of [Data Set Message Header](https://reference.opcfoundation.org/Core/Part14/v105/docs/7.2.5.4#Table164) field `MetaDataVersion`. +- Type: `Integer` +- Description: Links dataset message to the current version of the metadata. Contains value from `MajorVersion` of [Data Set Message Header](https://reference.opcfoundation.org/Core/Part14/v105/docs/7.2.5.4#Table164) field `MetaDataVersion`. +- Constraints + - OPTIONAL + - Can be omitted if `dataschema` is used + +### opcuametadataminorversion + +- Type: `Integer` +- Description: Links dataset message to the current version of the metadata. Contains value from `MiniorVersion` of [Data Set Message Header](https://reference.opcfoundation.org/Core/Part14/v105/docs/7.2.5.4#Table164) field `MetaDataVersion`. - Constraints - OPTIONAL - Can be omitted if `dataschema` is used @@ -88,4 +96,6 @@ Attribute as defined by [recordedtime extension](./recordedtime.md) SHALL be use ## General Constraints -- OPC UA messages always use `binary-mode`. +- OPC UA messages MUST use `binary-mode` of Cloud Events. +- OPC UA PubSub JSON messages MUST be encoded using non-reversible encoding as the decoding information are contained in metadata messages or by schema referenced via `dataschema` attribute. +- Payload of OPC UA PubSub JSON messages MUST NOT contain Network Message Header and Data Set Header as those information are mapped into Cloud Events attributes. From 44f2d318d396e26b4cb1039a13e1940ad653c426 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alexander=20K=C3=B6pke?= Date: Tue, 26 Mar 2024 16:21:49 +0000 Subject: [PATCH 04/14] Add SingleDataSetMessage constraint MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Alexander Köpke --- cloudevents/extensions/opcua.md | 1 + 1 file changed, 1 insertion(+) diff --git a/cloudevents/extensions/opcua.md b/cloudevents/extensions/opcua.md index ebe55799e..bc804cfc0 100644 --- a/cloudevents/extensions/opcua.md +++ b/cloudevents/extensions/opcua.md @@ -99,3 +99,4 @@ Attribute as defined by [recordedtime extension](./recordedtime.md) SHALL be use - OPC UA messages MUST use `binary-mode` of Cloud Events. - OPC UA PubSub JSON messages MUST be encoded using non-reversible encoding as the decoding information are contained in metadata messages or by schema referenced via `dataschema` attribute. - Payload of OPC UA PubSub JSON messages MUST NOT contain Network Message Header and Data Set Header as those information are mapped into Cloud Events attributes. +- OPC UA PubSub JSON messages MUST only contain one dataset message. From 4b455e6689fb5de247a15b995a7a9204cf553d80 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alexander=20K=C3=B6pke?= Date: Tue, 26 Mar 2024 18:40:55 +0000 Subject: [PATCH 05/14] type need to reference DataSetMessage.MessageType MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Alexander Köpke --- cloudevents/extensions/opcua.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cloudevents/extensions/opcua.md b/cloudevents/extensions/opcua.md index bc804cfc0..ff3049af7 100644 --- a/cloudevents/extensions/opcua.md +++ b/cloudevents/extensions/opcua.md @@ -26,7 +26,7 @@ MUST either map to [Application Description](https://reference.opcfoundation.org ### type -MUST map to [Network Message Header](https://reference.opcfoundation.org/Core/Part14/v105/docs/7.2.5.3#Table163) field `MessageType`. +MUST map to [Data Set Message Header](https://reference.opcfoundation.org/Core/Part14/v105/docs/7.2.5.4#Table164) field `MessageType`. ## Mapping of OPTIONAL Attributes From 7a28d598c1eaa6cab1529b107d8e618c4eda3b4e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alexander=20K=C3=B6pke?= Date: Wed, 27 Mar 2024 18:42:54 +0000 Subject: [PATCH 06/14] fixed spec verification findings MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Alexander Köpke --- cloudevents/extensions/opcua.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/cloudevents/extensions/opcua.md b/cloudevents/extensions/opcua.md index ff3049af7..3477e964c 100644 --- a/cloudevents/extensions/opcua.md +++ b/cloudevents/extensions/opcua.md @@ -1,6 +1,6 @@ # OPC UA -This extension defines the mapping of OPC UA dataset to cloud events to allow seamless routing of OPC UA dataset messages via different protocols, it therefor provides an recommendation to map known mandatory and optional attributes using other extensions as well as defines own extended attributes. +This extension defines the mapping of OPC UA dataset to CloudEvents to allow seamless routing of OPC UA dataset messages via different protocols, it therefor provides an recommendation to map known MANDATORY and OPTIONAL attributes using other extensions as well as defines own extended attributes. ## Notational Conventions @@ -36,7 +36,7 @@ SHALL be `application/opcua+json` for OPC UA PubSub JSON payload and MAY be exte ### dataschema -OPC UA provides type information as part of PubSub metadata messages, for non OPC UA consumers or when different payload encoding like Avro is used, it is required to provide schema information (based on metadata information) in a separate format like [JSON schema](https://json-schema.org/specification) or [Avro schema](https://avro.apache.org/docs/1.11.1/specification/) or others. For those cases the Attribute references the schema and is used for versioning. +OPC UA provides type information as part of PubSub metadata messages, for non OPC UA consumers or when different payload encoding like Avro is used, it is REQUIRED to provide schema information (based on metadata information) in a separate format like [JSON schema](https://json-schema.org/specification) or [Avro schema](https://avro.apache.org/docs/1.11.1/specification/) or others. For those cases the Attribute references the schema and is used for versioning. ### subject @@ -96,7 +96,7 @@ Attribute as defined by [recordedtime extension](./recordedtime.md) SHALL be use ## General Constraints -- OPC UA messages MUST use `binary-mode` of Cloud Events. +- OPC UA messages MUST use `binary-mode` of CloudEvents. - OPC UA PubSub JSON messages MUST be encoded using non-reversible encoding as the decoding information are contained in metadata messages or by schema referenced via `dataschema` attribute. -- Payload of OPC UA PubSub JSON messages MUST NOT contain Network Message Header and Data Set Header as those information are mapped into Cloud Events attributes. +- Payload of OPC UA PubSub JSON messages MUST NOT contain Network Message Header and Data Set Header as those information are mapped into CloudEvents attributes. - OPC UA PubSub JSON messages MUST only contain one dataset message. From 9e872eae48de9411fe55c9b286c754ec65645da4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alexander=20K=C3=B6pke?= Date: Wed, 27 Mar 2024 18:49:39 +0000 Subject: [PATCH 07/14] Added translation files MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Alexander Köpke --- cloudevents/languages/he/extensions/opcua.md | 2 ++ cloudevents/languages/zh-CN/extensions/opcua.md | 6 ++++++ 2 files changed, 8 insertions(+) create mode 100644 cloudevents/languages/he/extensions/opcua.md create mode 100644 cloudevents/languages/zh-CN/extensions/opcua.md diff --git a/cloudevents/languages/he/extensions/opcua.md b/cloudevents/languages/he/extensions/opcua.md new file mode 100644 index 000000000..43bb9ff22 --- /dev/null +++ b/cloudevents/languages/he/extensions/opcua.md @@ -0,0 +1,2 @@ +# OPC UA +מסמך זה טרם תורגם. בבקשה תשתמשו [בגרסה האנגלית של המסמך](../../../extensions/opcua.md) לבינתיים. diff --git a/cloudevents/languages/zh-CN/extensions/opcua.md b/cloudevents/languages/zh-CN/extensions/opcua.md new file mode 100644 index 000000000..850297aa9 --- /dev/null +++ b/cloudevents/languages/zh-CN/extensions/opcua.md @@ -0,0 +1,6 @@ +# OPC UA + +本文档尚未被翻译，请先阅读英文[原版文档](../../../extensions/opcua.md) 。 + +如果您迫切地需要此文档的中文翻译，请[提交一个issue](https://github.com/cloudevents/spec/issues) ， +我们会尽快安排专人进行翻译。 From 96c5fdb0bedbb0193d8ad1f5de095741abf8d659 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alexander=20K=C3=B6pke?= Date: Wed, 27 Mar 2024 19:05:41 +0000 Subject: [PATCH 08/14] integrated review feedback MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Alexander Köpke --- cloudevents/extensions/README.md | 2 +- cloudevents/extensions/opcua.md | 82 +++++++++++++++++++++++--------- 2 files changed, 60 insertions(+), 24 deletions(-) diff --git a/cloudevents/extensions/README.md b/cloudevents/extensions/README.md index 4986b5fed..688c2555f 100644 --- a/cloudevents/extensions/README.md +++ b/cloudevents/extensions/README.md @@ -44,9 +44,9 @@ for more information. - [Dataref (Claim Check Pattern)](dataref.md) - [Distributed Tracing](distributed-tracing.md) - [Expiry Time](expirytime.md) +- [OPC UA](opcua.md) - [Partitioning](partitioning.md) - [Recorded Time](recordedtime.md) - [Sampling](sampledrate.md) - [Sequence](sequence.md) - [Severity](severity.md) -- [OPC UA](opcua.md) diff --git a/cloudevents/extensions/opcua.md b/cloudevents/extensions/opcua.md index 3477e964c..8db6bb52e 100644 --- a/cloudevents/extensions/opcua.md +++ b/cloudevents/extensions/opcua.md @@ -1,6 +1,10 @@ # OPC UA -This extension defines the mapping of OPC UA dataset to CloudEvents to allow seamless routing of OPC UA dataset messages via different protocols, it therefor provides an recommendation to map known MANDATORY and OPTIONAL attributes using other extensions as well as defines own extended attributes. +This extension defines the mapping of OPC UA dataset to CloudEvents to allow +seamless routing of OPC UA dataset messages via different protocols, it +therefore provides a recommendation to map known REQUIRED and OPTIONAL +attributes using other extensions as well as defines its own extension +attributes. ## Notational Conventions @@ -9,20 +13,25 @@ As with the main [CloudEvents specification](../spec.md), the key words "MUST", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119). -However, the scope of these key words is limited to when this extension is -used. For example, an attribute being marked as "REQUIRED" does not mean -it needs to be in all CloudEvents, rather it needs to be included only when -this extension is being used. +However, the scope of these key words is limited to when this extension is used. +For example, an attribute being marked as "REQUIRED" does not mean it needs to +be in all CloudEvents, rather it needs to be included only when this extension +is being used. ## Mapping of REQUIRED Attributes ### id -MUST map to [Network Message Header](https://reference.opcfoundation.org/Core/Part14/v105/docs/7.2.5.3#Table163) field `MessageId`. +MUST map to [Network Message +Header](https://reference.opcfoundation.org/Core/Part14/v105/docs/7.2.5.3#Table163) +field `MessageId`. ### source -MUST either map to [Application Description](https://reference.opcfoundation.org/Core/Part4/v104/docs/7.1) field `applicationUri` of the OPC UA server or to an customer configured identifier like an unified namespace path. +MUST either map to [Application +Description](https://reference.opcfoundation.org/Core/Part4/v104/docs/7.1) field +`applicationUri` of the OPC UA server or to a customer configured identifier +like a unified namespace path. ### type @@ -32,56 +41,79 @@ MUST map to [Data Set Message Header](https://reference.opcfoundation.org/Core/P ### datacontenttype -SHALL be `application/opcua+json` for OPC UA PubSub JSON payload and MAY be extended by `+gzip` when payload is gzip compressed. +MUST be `application/json` for OPC UA PubSub JSON payload and MAY be extended by +`+gzip` when payload is gzip compressed. ### dataschema -OPC UA provides type information as part of PubSub metadata messages, for non OPC UA consumers or when different payload encoding like Avro is used, it is REQUIRED to provide schema information (based on metadata information) in a separate format like [JSON schema](https://json-schema.org/specification) or [Avro schema](https://avro.apache.org/docs/1.11.1/specification/) or others. For those cases the Attribute references the schema and is used for versioning. +OPC UA provides type information as part of PubSub metadata messages, for non +OPC UA consumers or when different payload encoding like Avro is used, it is +REQUIRED to provide schema information (based on metadata information) in a +separate format like [JSON schema](https://json-schema.org/specification) or +[Avro schema](https://avro.apache.org/docs/1.11.1/specification/) or others. For +those cases the Attribute references the schema and is used for versioning. ### subject -For metadata and data messages (type one of `ua-metadata`, `ua-keyframe`, `ua-deltaframe`) MUST map to either [Data Set Message Header](https://reference.opcfoundation.org/Core/Part14/v105/docs/7.2.5.4#Table164) field `DataSetWriterId` or `DataSetWriterName`. +For metadata and data messages (type one of `ua-metadata`, `ua-keyframe`, +`ua-deltaframe`), `subject` MUST map to either [Data Set Message +Header](https://reference.opcfoundation.org/Core/Part14/v105/docs/7.2.5.4#Table164) +field `DataSetWriterId` or `DataSetWriterName`. -For event messages (type equals to `ua-event`) SHALL map to [Base Event Type](https://reference.opcfoundation.org/Core/Part5/v104/docs/6.4.2) field `EventId`. +For event messages (type equals to `ua-event`) `subject` MUST map to [Base Event +Type](https://reference.opcfoundation.org/Core/Part5/v104/docs/6.4.2) field +`EventId`. ### time -MUST map to [Data Set Message Header](https://reference.opcfoundation.org/Core/Part14/v105/docs/7.2.5.4#Table164) field `Timestamp`. +MUST map to [Data Set Message +Header](https://reference.opcfoundation.org/Core/Part14/v105/docs/7.2.5.4#Table164) +field `Timestamp`. ## Mapping for other extensions -The following well-known extensions attributes are used for data messages and event messages (type one of `ua-keyframe`, `ua-deltaframe`, `ua-event`). +The following well-known extensions attributes are used for data messages and +event messages (type one of `ua-keyframe`, `ua-deltaframe`, `ua-event`). ### sequence -Attribute as defined by [sequence extensions](./sequence.md) MUST map to [Data Set Message Header](https://reference.opcfoundation.org/Core/Part14/v105/docs/7.2.5.4#Table164) field `SequenceNumber`. +Attribute as defined by [sequence extensions](./sequence.md) MUST map to [Data +Set Message Header](https://reference.opcfoundation.org/Core/Part14/v105/docs/7.2.5.4#Table164) +field `SequenceNumber`. ### traceparent -Attribute as defined by [distributed-tracing extension](./distributed-tracing.md) SHALL be used to allow tracing from event publisher towards consumer. +Attribute as defined by [distributed-tracing extension](./distributed-tracing.md) +MUST be used to allow tracing from event publisher towards consumer. ### tracestate -Attribute as defined by [distributed-tracing extension](./distributed-tracing.md) might OPTIONAL be used to allow tracing from event publisher towards consumer. +Attribute as defined by [distributed-tracing extension](./distributed-tracing.md) +MAY be used to allow tracing from event publisher towards consumer. ### recordedtime -Attribute as defined by [recordedtime extension](./recordedtime.md) SHALL be used to determine the latency between event publisher towards consumer. +Attribute as defined by [recordedtime extension](./recordedtime.md) MUST be used +to determine the latency between event publisher towards consumer. ## Attributes ### opcuametadatamajorversion - Type: `Integer` -- Description: Links dataset message to the current version of the metadata. Contains value from `MajorVersion` of [Data Set Message Header](https://reference.opcfoundation.org/Core/Part14/v105/docs/7.2.5.4#Table164) field `MetaDataVersion`. +- Description: Links dataset message to the current version of the metadata. +Contains value from `MajorVersion` of [Data Set Message Header](https://reference.opcfoundation.org/Core/Part14/v105/docs/7.2.5.4#Table164) field `MetaDataVersion`. - Constraints - OPTIONAL - - Can be omitted if `dataschema` is used + - MAY be omitted if `dataschema` is used ### opcuametadataminorversion - Type: `Integer` -- Description: Links dataset message to the current version of the metadata. Contains value from `MiniorVersion` of [Data Set Message Header](https://reference.opcfoundation.org/Core/Part14/v105/docs/7.2.5.4#Table164) field `MetaDataVersion`. +- Description: Links dataset message to the current version of the metadata. +Contains value from `MiniorVersion` of [Data Set Message +Header](https://reference.opcfoundation.org/Core/Part14/v105/docs/7.2.5.4#Table164) +field `MetaDataVersion`. - Constraints - OPTIONAL - Can be omitted if `dataschema` is used @@ -89,7 +121,8 @@ Attribute as defined by [recordedtime extension](./recordedtime.md) SHALL be use ### opcuastatus - Type: `Integer` -- Description: Defines the overall status of the data set message, maps to [Data Set Message Header](https://reference.opcfoundation.org/Core/Part14/v105/docs/7.2.5.4#Table164) field `Status`. +- Description: Defines the overall status of the data set message, maps to +[Data Set Message Header](https://reference.opcfoundation.org/Core/Part14/v105/docs/7.2.5.4#Table164) field `Status`. - Constraints - OPTIONAL - Can be omitted if status is _Good_ @@ -97,6 +130,9 @@ Attribute as defined by [recordedtime extension](./recordedtime.md) SHALL be use ## General Constraints - OPC UA messages MUST use `binary-mode` of CloudEvents. -- OPC UA PubSub JSON messages MUST be encoded using non-reversible encoding as the decoding information are contained in metadata messages or by schema referenced via `dataschema` attribute. -- Payload of OPC UA PubSub JSON messages MUST NOT contain Network Message Header and Data Set Header as those information are mapped into CloudEvents attributes. +- OPC UA PubSub JSON messages MUST be encoded using non-reversible encoding as +the decoding information is contained in metadata messages or by schema +referenced via `dataschema` attribute. +- Payload of OPC UA PubSub JSON messages MUST NOT contain Network Message Header +and Data Set Header as those information are mapped into CloudEvents attributes. - OPC UA PubSub JSON messages MUST only contain one dataset message. From c6478597a9f4cff2543feb99d0587499565f543f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alexander=20K=C3=B6pke?= Date: Wed, 27 Mar 2024 19:33:54 +0000 Subject: [PATCH 09/14] added references to OPC UA and OPC UA PubSub MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Alexander Köpke --- cloudevents/extensions/opcua.md | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/cloudevents/extensions/opcua.md b/cloudevents/extensions/opcua.md index 8db6bb52e..15f3392b7 100644 --- a/cloudevents/extensions/opcua.md +++ b/cloudevents/extensions/opcua.md @@ -1,9 +1,10 @@ # OPC UA -This extension defines the mapping of OPC UA dataset to CloudEvents to allow -seamless routing of OPC UA dataset messages via different protocols, it -therefore provides a recommendation to map known REQUIRED and OPTIONAL -attributes using other extensions as well as defines its own extension +This extension defines the mapping of [OPC UA](https://reference.opcfoundation.org/Core/Part1/v105/docs/) +[PubSub](https://reference.opcfoundation.org/Core/Part14/v105/docs/) dataset to +CloudEvents to allow seamless routing of OPC UA dataset messages via different +protocols, it therefore provides a recommendation to map known REQUIRED and +OPTIONAL attributes using other extensions as well as defines its own extension attributes. ## Notational Conventions @@ -35,7 +36,8 @@ like a unified namespace path. ### type -MUST map to [Data Set Message Header](https://reference.opcfoundation.org/Core/Part14/v105/docs/7.2.5.4#Table164) field `MessageType`. +MUST map to [Data Set Message Header](https://reference.opcfoundation.org/Core/Part14/v105/docs/7.2.5.4#Table164) +field `MessageType`. ## Mapping of OPTIONAL Attributes @@ -116,7 +118,7 @@ Header](https://reference.opcfoundation.org/Core/Part14/v105/docs/7.2.5.4#Table1 field `MetaDataVersion`. - Constraints - OPTIONAL - - Can be omitted if `dataschema` is used + - MAY be omitted if `dataschema` is used ### opcuastatus @@ -125,7 +127,7 @@ field `MetaDataVersion`. [Data Set Message Header](https://reference.opcfoundation.org/Core/Part14/v105/docs/7.2.5.4#Table164) field `Status`. - Constraints - OPTIONAL - - Can be omitted if status is _Good_ + - MAY be omitted if status is _Good_ ## General Constraints From 1cf507b64723eedc437c71e35efdd53ea024063c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alexander=20K=C3=B6pke?= Date: Wed, 27 Mar 2024 20:56:36 +0000 Subject: [PATCH 10/14] clarified opcuametadataversion usage when dataschema is used MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Alexander Köpke --- cloudevents/extensions/opcua.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/cloudevents/extensions/opcua.md b/cloudevents/extensions/opcua.md index 15f3392b7..2f723ca0c 100644 --- a/cloudevents/extensions/opcua.md +++ b/cloudevents/extensions/opcua.md @@ -106,8 +106,7 @@ to determine the latency between event publisher towards consumer. - Description: Links dataset message to the current version of the metadata. Contains value from `MajorVersion` of [Data Set Message Header](https://reference.opcfoundation.org/Core/Part14/v105/docs/7.2.5.4#Table164) field `MetaDataVersion`. - Constraints - - OPTIONAL - - MAY be omitted if `dataschema` is used + - OPTIONAL but MUST NOT be present if `dataschema` is used ### opcuametadataminorversion @@ -117,8 +116,7 @@ Contains value from `MiniorVersion` of [Data Set Message Header](https://reference.opcfoundation.org/Core/Part14/v105/docs/7.2.5.4#Table164) field `MetaDataVersion`. - Constraints - - OPTIONAL - - MAY be omitted if `dataschema` is used + - OPTIONAL but MUST NOT be present if `dataschema` is used ### opcuastatus From 91c30b136d2577ce3b7db5be5df17309192858a8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alexander=20K=C3=B6pke?= Date: Thu, 28 Mar 2024 22:52:34 +0000 Subject: [PATCH 11/14] Added examples; corrected subject for events; explained use cases and benefits MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Alexander Köpke --- cloudevents/extensions/opcua.md | 207 +++++++++++++++++++++++++++++++- 1 file changed, 202 insertions(+), 5 deletions(-) diff --git a/cloudevents/extensions/opcua.md b/cloudevents/extensions/opcua.md index 2f723ca0c..6f19d10ef 100644 --- a/cloudevents/extensions/opcua.md +++ b/cloudevents/extensions/opcua.md @@ -57,14 +57,14 @@ those cases the Attribute references the schema and is used for versioning. ### subject -For metadata and data messages (type one of `ua-metadata`, `ua-keyframe`, -`ua-deltaframe`), `subject` MUST map to either [Data Set Message +For metadata, event and data messages (type one of `ua-metadata`, `ua-keyframe`, +`ua-deltaframe`, `ua-event`), `subject` MUST map to either [Data Set Message Header](https://reference.opcfoundation.org/Core/Part14/v105/docs/7.2.5.4#Table164) field `DataSetWriterId` or `DataSetWriterName`. -For event messages (type equals to `ua-event`) `subject` MUST map to [Base Event -Type](https://reference.opcfoundation.org/Core/Part5/v104/docs/6.4.2) field -`EventId`. +For event messages (type equals to `ua-event`) `subject` MUST additional contain +"/" and [Base Event Type](https://reference.opcfoundation.org/Core/Part5/v104/docs/6.4.2) +field `EventId`. ### time @@ -136,3 +136,200 @@ referenced via `dataschema` attribute. - Payload of OPC UA PubSub JSON messages MUST NOT contain Network Message Header and Data Set Header as those information are mapped into CloudEvents attributes. - OPC UA PubSub JSON messages MUST only contain one dataset message. + +## Examples + +### Metadata message + +The metadata message help Cloud applications to understand the semantics and +structure of dataset messages. + +```text +------------------ PUBLISH ------------------- + +Topic Name: opcua/json/DataSetMetaData/publisher-on-ot-edge +Content Type: application/json; charset=utf-8 + +------------- User Properties ---------------- + +specversion: 1.0 +type: ua-metadata +time: 2024-03-28T21:56:24Z +id: 1234-1234-1234 +source: urn:factory:aggregationserver:opcua +datacontenttype: application/json; charset=utf-8 +subject: energy-consumption-asset + .... further attributes ... + +------------------ payload ------------------- + +{ + ... application data (OPC UA PubSub metadata) ... + "ConfigurationVersion": { + "MajorVersion": 672338910, + "MinorVersion": 672341762 + } + ... +} + +----------------------------------------------- +``` + +### Telemetry message + +The telemetry or data messages contain values of all OPC UA nodes that had +changed in a given period of time (`ua-deltaframe`) or contain values for all +OPC UA nodes that were monitored (`ua-keyframe`). +The complete list of monitored OPC UA nodes as well as the related type +information are defined in the metadata message. The attributes +`opcuametadatamajorversion` and `opcuametadataminorversion` are used to +reference the correct metadata message. The `ua-deltaframe` messages will be +used for hot and/or cold path processing and `ua-keyframe` messages can +additional be used to update last-known-value tables. + + +```text +------------------ PUBLISH ------------------- + +Topic Name: opcua/json/DataSetMessage/publisher-on-ot-edge +Content Type: application/json; charset=utf-8 + +------------- User Properties ---------------- + +specversion: 1.0 +type: ua-deltaframe +time: 2024-03-28T21:56:42Z +id: 1235-1235-1235 +source: urn:factory:aggregationserver:opcua +datacontenttype: application/json; charset=utf-8 +subject: energy-consumption-asset +sequence: 7 +traceparent: 4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00000011 +recordedtime: 2024-03-28T21:56:43Z +opcuametadatamajorversion: 672338910 +opcuametadataminorversion: 672341762 + .... further attributes ... + +------------------ payload ------------------- + +{ + ... application data + (OPC UA PubSub JSON single dataset Message)... +} + +----------------------------------------------- +``` + +#### OPC UA PubSub JSON single dataset Message + +Using CloudEvents and model the OPC UA PubSub header information as CloudEvent +attributes enables integration into various system (independent from used +protocols) and simplifies the payload structure. + +```text +{ + "IsRunning": { + "Value": true, + "SourceTimestamp": "2024-03-29T07:31:19.555Z" + }, + "EnergyConsumption": { + "Value": 31 + "SourceTimestamp": "2024-03-29T07:31:37.546Z", + "StatusCode": { + "Code":1073741824, + "Symbol":"Uncertain" + } + }, + "EnergyPeak": { + "Value": 54 + "SourceTimestamp": "2024-03-29T07:31:06.978Z" + }, + "EnergyLow": { + "Value": 22 + "SourceTimestamp": "2024-03-29T07:31:17.582Z" + } +} + +``` + +### Event message + +The event message will contain a single event and the identifier of this event is +added to the `subject` to allow routing it into different systems without parsing +the payload. Events are routed for example in systems like Manufacturing Execution +Systems (MES), Supervisory Control and Data Acquisition systems (SCADA), +Alerting Systems or Operation Technology Operator Terminals (HMI Clients) and +also in hot and/or cold path processing. The attributes +`opcuametadatamajorversion` and `opcuametadataminorversion` are used to +reference the correct metadata message. + +```text +------------------ PUBLISH ------------------- + +Topic Name: opcua/json/DataSetMessage/publisher-on-ot-edge +Content Type: application/json; charset=utf-8 + +------------- User Properties ---------------- + +specversion: 1.0 +type: ua-event +time: 2024-03-28T21:57:01Z +id: 1236-1237-1238 +source: urn:factory:aggregationserver:opcua +datacontenttype: application/json; charset=utf-8 +subject: energy-consumption-asset/444321 +sequence: 18 +traceparent: caffef3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00000011 +recordedtime: 2024-03-28T21:57:01Z +opcuametadatamajorversion: 672338910 +opcuametadataminorversion: 672341762 + .... further attributes ... + +------------------ payload ------------------- + +{ + ... application data + (OPC UA PubSub JSON Single Event Message)... +} + +----------------------------------------------- +``` + +### Telemetry message with different Encoding + +One major benefit of CloudEvents for OPC UA is that it is possible to support +other encoding and external schema, while keeping the same OPC UA information for +routing. + +The example below uses Avro binary encoded payload, with the corresponding schema +referenced by `dataschema`. The `source` will be defined by an customer defined +hierarchical path. + +```text +------------------ PUBLISH ------------------- + +Topic Name: bottling-company/amsterdam/FillingArea1/FillingLine9/Cell1/Conveyor +Content Type: application/avro + +------------- User Properties ---------------- + +specversion: 1.0 +type: ua-keyframe +time: 2024-03-28T23:59:59Z +id: 6235-7235-8235 +source: bottling-company/amsterdam/FillingArea1/FillingLine9/Cell1/Conveyor +datacontenttype: application/avro +subject: energy-consumption-asset +dataschema: http://example.com/schemas/energy-consumption-asset/v1.8 +sequence: 3141 +traceparent: 22222f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00000011 +recordedtime: 2024-03-28T23:59:59Z + .... further attributes ... + +------------------ payload ------------------- + + ... application data + (OPC UA PubSub Single DataSet Message as AVRO binary)... + +----------------------------------------------- +``` From 2666af61b581b73f6e155604697f6b37f2232d4b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alexander=20K=C3=B6pke?= Date: Wed, 3 Apr 2024 08:50:04 +0000 Subject: [PATCH 12/14] Addressed review feedback MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Alexander Köpke --- cloudevents/extensions/opcua.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/cloudevents/extensions/opcua.md b/cloudevents/extensions/opcua.md index 6f19d10ef..1532b27a0 100644 --- a/cloudevents/extensions/opcua.md +++ b/cloudevents/extensions/opcua.md @@ -43,8 +43,8 @@ field `MessageType`. ### datacontenttype -MUST be `application/json` for OPC UA PubSub JSON payload and MAY be extended by -`+gzip` when payload is gzip compressed. +MUST be `application/json` for OPC UA PubSub JSON payload and MAY be appended with +`+gzip` when the payload is gzip compressed. ### dataschema @@ -53,7 +53,7 @@ OPC UA consumers or when different payload encoding like Avro is used, it is REQUIRED to provide schema information (based on metadata information) in a separate format like [JSON schema](https://json-schema.org/specification) or [Avro schema](https://avro.apache.org/docs/1.11.1/specification/) or others. For -those cases the Attribute references the schema and is used for versioning. +those cases the attribute references the schema and is used for versioning. ### subject @@ -62,7 +62,7 @@ For metadata, event and data messages (type one of `ua-metadata`, `ua-keyframe`, Header](https://reference.opcfoundation.org/Core/Part14/v105/docs/7.2.5.4#Table164) field `DataSetWriterId` or `DataSetWriterName`. -For event messages (type equals to `ua-event`) `subject` MUST additional contain +For event messages (type equals to `ua-event`) `subject` MUST be appended with "/" and [Base Event Type](https://reference.opcfoundation.org/Core/Part5/v104/docs/6.4.2) field `EventId`. @@ -125,6 +125,7 @@ field `MetaDataVersion`. [Data Set Message Header](https://reference.opcfoundation.org/Core/Part14/v105/docs/7.2.5.4#Table164) field `Status`. - Constraints - OPTIONAL + - REQUIRED if status is not _Good_ - MAY be omitted if status is _Good_ ## General Constraints @@ -134,14 +135,14 @@ field `MetaDataVersion`. the decoding information is contained in metadata messages or by schema referenced via `dataschema` attribute. - Payload of OPC UA PubSub JSON messages MUST NOT contain Network Message Header -and Data Set Header as those information are mapped into CloudEvents attributes. -- OPC UA PubSub JSON messages MUST only contain one dataset message. +and Data Set Header as that information is mapped into CloudEvents attributes. +- OPC UA PubSub JSON messages MUST contain exactly one dataset message. ## Examples ### Metadata message -The metadata message help Cloud applications to understand the semantics and +The metadata message helps Cloud applications to understand the semantics and structure of dataset messages. ```text From 34a287666cd8012a56211590ca0de1cc312599d5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alexander=20K=C3=B6pke?= Date: Wed, 3 Apr 2024 09:02:30 +0000 Subject: [PATCH 13/14] clarify usage of traceparent and recordedtime MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Alexander Köpke --- cloudevents/extensions/opcua.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/cloudevents/extensions/opcua.md b/cloudevents/extensions/opcua.md index 1532b27a0..4b78ac729 100644 --- a/cloudevents/extensions/opcua.md +++ b/cloudevents/extensions/opcua.md @@ -86,7 +86,8 @@ field `SequenceNumber`. ### traceparent Attribute as defined by [distributed-tracing extension](./distributed-tracing.md) -MUST be used to allow tracing from event publisher towards consumer. +MUST be present in all OPC UA enabled CloudEvents to allow tracing from event +publisher towards consumer. ### tracestate @@ -95,8 +96,9 @@ MAY be used to allow tracing from event publisher towards consumer. ### recordedtime -Attribute as defined by [recordedtime extension](./recordedtime.md) MUST be used -to determine the latency between event publisher towards consumer. +Attribute as defined by [recordedtime extension](./recordedtime.md) MUST be +present in all OPC UA enabled CloudEvents to determine the latency between +event publisher towards consumer. ## Attributes From 11313e25b4e6f07362e125536914344609055b10 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alexander=20K=C3=B6pke?= Date: Thu, 4 Apr 2024 08:51:25 +0000 Subject: [PATCH 14/14] fixed typo Minior -> Minor; clarify usage of extension attributes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Alexander Köpke --- cloudevents/extensions/opcua.md | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/cloudevents/extensions/opcua.md b/cloudevents/extensions/opcua.md index 4b78ac729..fbbfa7fbc 100644 --- a/cloudevents/extensions/opcua.md +++ b/cloudevents/extensions/opcua.md @@ -74,7 +74,7 @@ field `Timestamp`. ## Mapping for other extensions -The following well-known extensions attributes are used for data messages and +The following well-known extensions attributes MUST be used for data messages and event messages (type one of `ua-keyframe`, `ua-deltaframe`, `ua-event`). ### sequence @@ -86,8 +86,7 @@ field `SequenceNumber`. ### traceparent Attribute as defined by [distributed-tracing extension](./distributed-tracing.md) -MUST be present in all OPC UA enabled CloudEvents to allow tracing from event -publisher towards consumer. +to allow tracing from event publisher towards consumer. ### tracestate @@ -96,9 +95,8 @@ MAY be used to allow tracing from event publisher towards consumer. ### recordedtime -Attribute as defined by [recordedtime extension](./recordedtime.md) MUST be -present in all OPC UA enabled CloudEvents to determine the latency between -event publisher towards consumer. +Attribute as defined by [recordedtime extension](./recordedtime.md) to +determine the latency between event publisher towards consumer. ## Attributes @@ -114,7 +112,7 @@ Contains value from `MajorVersion` of [Data Set Message Header](https://referenc - Type: `Integer` - Description: Links dataset message to the current version of the metadata. -Contains value from `MiniorVersion` of [Data Set Message +Contains value from `MinorVersion` of [Data Set Message Header](https://reference.opcfoundation.org/Core/Part14/v105/docs/7.2.5.4#Table164) field `MetaDataVersion`. - Constraints