From e9cb35f1ab29adfd536e8999883dca233be751f0 Mon Sep 17 00:00:00 2001 From: Dominik Oeh Date: Wed, 5 Jul 2023 10:12:22 +0200 Subject: [PATCH 1/8] feat: add aspect model for the shared message header --- .../1.0.0/MessageHeaderAspect.ttl | 126 ++++++++++++++++++ io.catenax.message_header/1.0.0/metadata.json | 1 + io.catenax.message_header/RELEASE_NOTES.md | 7 + 3 files changed, 134 insertions(+) create mode 100644 io.catenax.message_header/1.0.0/MessageHeaderAspect.ttl create mode 100644 io.catenax.message_header/1.0.0/metadata.json create mode 100644 io.catenax.message_header/RELEASE_NOTES.md diff --git a/io.catenax.message_header/1.0.0/MessageHeaderAspect.ttl b/io.catenax.message_header/1.0.0/MessageHeaderAspect.ttl new file mode 100644 index 00000000..71cdd1d9 --- /dev/null +++ b/io.catenax.message_header/1.0.0/MessageHeaderAspect.ttl @@ -0,0 +1,126 @@ +@prefix samm: . +@prefix samm-c: . +@prefix samm-e: . +@prefix unit: . +@prefix rdf: . +@prefix rdfs: . +@prefix xsd: . +@prefix : . + +:MessageHeaderAspect a samm:Aspect ; + samm:preferredName "Message Header Aspect"@en ; + samm:description "Aspect model describing the message header which must be included in every message"@en ; + samm:properties ( :header ) ; + samm:operations ( ) ; + samm:events ( ) . + +:header a samm:Property ; + samm:preferredName "header"@en ; + samm:description "Contains information common to all messages"@en ; + samm:characteristic :HeaderCharacteristic . + +:HeaderCharacteristic a samm:Characteristic ; + samm:preferredName "Header Characteristic"@en ; + samm:description "Characteristic describing the common shared aspect Message Header"@en ; + samm:dataType :MessageHeader . + +:MessageHeader a samm:Entity ; + samm:preferredName "Message Header"@en ; + samm:description "The header that must be included in every message."@en ; + samm:properties ( :messageId :context :sentDateTime :senderBpn :receiverBpn [ samm:property :expectedResponseBy; samm:optional true ] [ samm:property :relatedMessageId; samm:optional true ] :version ) . + +:messageId a samm:Property ; + samm:preferredName "Message ID"@en ; + samm:description """Unique ID identifying the message. + +The purpose of the ID is to uniquely identify a single message, therefore it MUST not be reused."""@en ; + samm:characteristic :UuidCharacteristic ; + samm:exampleValue "3b4edc05-e214-47a1-b0c2-1d831cdd9ba9" . + +:context a samm:Property ; + samm:preferredName "Context"@en ; + samm:description """Information about the context the message should be considered in. + +Default: For Use Cases which need to validate against the Semantic Hub automatically. + +Fallback: For Use Cases which do not use automatic validation. + +In both cases: Versioning only refers to major versions. + +String pattern of the value follows: ---"""@en ; + samm:characteristic :ContextCharacteristic ; + samm:exampleValue "urn:samm:io.catenax.:1.x.x" . + +:sentDateTime a samm:Property ; + samm:preferredName "Sent Date Time"@en ; + samm:description """Time zone aware timestamp holding the date and the time the message was sent by the sending party + +The value MUST be formatted according to the ISO 8601 standard"""@en ; + samm:characteristic :Timestamp ; + samm:exampleValue "2023-06-19T21:24:00+07:00"^^xsd:dateTimeStamp . + +:senderBpn a samm:Property ; + samm:preferredName "Sender BPN"@en ; + samm:description """The Business Partner Number of the sending party. + +The value MUST be a valid BPN. Applicable constraints are defined in the corresponding standard"""@en ; + samm:characteristic :BpnCharacteristic ; + samm:exampleValue "BPNL7588787849VQ" . + +:receiverBpn a samm:Property ; + samm:preferredName "Receiver BPN"@en ; + samm:description """The Business Partner Number of the receiving party. + +The value MUST be a valid BPN. Applicable constraints are defined in the corresponding standard."""@en ; + samm:characteristic :BpnCharacteristic ; + samm:exampleValue "BPNL6666787765VQ" . + +:expectedResponseBy a samm:Property ; + samm:preferredName "Expected Response By"@en ; + samm:description """Time zone aware timestamp holding the date and time by which the sending party expects a certain type of response from the receiving party. + +The meaning and interpretation of the fields's value are context-bound and MUST therefore be defined by any business domain or platform capability making use of it. + +The value MUST be formatted according to the ISO 8601 standard"""@en ; + samm:characteristic :Timestamp ; + samm:exampleValue "2023-06-19T21:24:00+07:00"^^xsd:dateTimeStamp . + +:relatedMessageId a samm:Property ; + samm:preferredName "Related Message ID"@en ; + samm:description "Unique ID identifying a message somehow related to the current one"@en ; + samm:characteristic :UuidCharacteristic ; + samm:exampleValue "d9452f24-3bf3-4134-b3eb-68858f1b2362" . + +:version a samm:Property ; + samm:preferredName "Version"@en ; + samm:description """The version of the standard defining the semantics and the structure of the message's header. + +The version number should follow the Semantic Versioning 2.0.0 specification"""@en ; + samm:characteristic :VersionCharacteristic ; + samm:exampleValue "urn:samm:io.catenax.message_header:1.0.0" . + +:UuidCharacteristic a samm:Characteristic ; + samm:preferredName "UUID Characteristic"@en ; + samm:description "Structured Value for defining a property which requires an UUID"@en ; + samm:dataType xsd:string . + +:ContextCharacteristic a samm:Characteristic ; + samm:preferredName "Context Characteristic"@en ; + samm:description "Defining a string value for the context"@en ; + samm:dataType xsd:string . + +:Timestamp a samm:Characteristic ; + samm:preferredName "Timestamp"@en ; + samm:description "Describes a Property which contains the date and time with an timezone."@en ; + samm:dataType xsd:dateTimeStamp . + +:BpnCharacteristic a samm:Characteristic ; + samm:preferredName "BPN Characteristic"@en ; + samm:description "Characteristic for defining BPN values"@en ; + samm:dataType xsd:string . + +:VersionCharacteristic a samm:Characteristic ; + samm:preferredName "Version Characteristic"@en ; + samm:description "Characteristic defining the value of version."@en ; + samm:dataType xsd:string . + diff --git a/io.catenax.message_header/1.0.0/metadata.json b/io.catenax.message_header/1.0.0/metadata.json new file mode 100644 index 00000000..84245e4e --- /dev/null +++ b/io.catenax.message_header/1.0.0/metadata.json @@ -0,0 +1 @@ +{ "status" : "release" } diff --git a/io.catenax.message_header/RELEASE_NOTES.md b/io.catenax.message_header/RELEASE_NOTES.md new file mode 100644 index 00000000..b0e7ee7a --- /dev/null +++ b/io.catenax.message_header/RELEASE_NOTES.md @@ -0,0 +1,7 @@ +# Changelog + +All notable changes to this model will be documented in this file. + +## [1.0.0] + +- initial version of the aspect model for the Message Header From 190bf5b0cc46da5f25196329ffff782c5a0547de Mon Sep 17 00:00:00 2001 From: Dominik Oeh Date: Fri, 7 Jul 2023 15:20:47 +0200 Subject: [PATCH 2/8] adding feedback to message header --- .../1.0.0/MessageHeaderAspect.ttl | 43 +++++-------------- 1 file changed, 10 insertions(+), 33 deletions(-) diff --git a/io.catenax.message_header/1.0.0/MessageHeaderAspect.ttl b/io.catenax.message_header/1.0.0/MessageHeaderAspect.ttl index 71cdd1d9..c76dae8b 100644 --- a/io.catenax.message_header/1.0.0/MessageHeaderAspect.ttl +++ b/io.catenax.message_header/1.0.0/MessageHeaderAspect.ttl @@ -9,13 +9,13 @@ :MessageHeaderAspect a samm:Aspect ; samm:preferredName "Message Header Aspect"@en ; - samm:description "Aspect model describing the message header which must be included in every message"@en ; + samm:description "Aspect model describing the message header, which must be included in every message"@en ; samm:properties ( :header ) ; samm:operations ( ) ; samm:events ( ) . :header a samm:Property ; - samm:preferredName "header"@en ; + samm:preferredName "Header"@en ; samm:description "Contains information common to all messages"@en ; samm:characteristic :HeaderCharacteristic . @@ -31,58 +31,42 @@ :messageId a samm:Property ; samm:preferredName "Message ID"@en ; - samm:description """Unique ID identifying the message. - -The purpose of the ID is to uniquely identify a single message, therefore it MUST not be reused."""@en ; + samm:description "Unique ID identifying the message. The purpose of the ID is to uniquely identify a single message, therefore it MUST not be reused."@en ; samm:characteristic :UuidCharacteristic ; samm:exampleValue "3b4edc05-e214-47a1-b0c2-1d831cdd9ba9" . :context a samm:Property ; samm:preferredName "Context"@en ; samm:description """Information about the context the message should be considered in. - Default: For Use Cases which need to validate against the Semantic Hub automatically. - Fallback: For Use Cases which do not use automatic validation. - In both cases: Versioning only refers to major versions. - String pattern of the value follows: ---"""@en ; samm:characteristic :ContextCharacteristic ; samm:exampleValue "urn:samm:io.catenax.:1.x.x" . :sentDateTime a samm:Property ; samm:preferredName "Sent Date Time"@en ; - samm:description """Time zone aware timestamp holding the date and the time the message was sent by the sending party - -The value MUST be formatted according to the ISO 8601 standard"""@en ; - samm:characteristic :Timestamp ; + samm:description "Time zone aware timestamp holding the date and the time the message was sent by the sending party. The value MUST be formatted according to the ISO 8601 standard"@en ; + samm:characteristic samm-c:Timestamp ; samm:exampleValue "2023-06-19T21:24:00+07:00"^^xsd:dateTimeStamp . :senderBpn a samm:Property ; samm:preferredName "Sender BPN"@en ; - samm:description """The Business Partner Number of the sending party. - -The value MUST be a valid BPN. Applicable constraints are defined in the corresponding standard"""@en ; + samm:description "The Business Partner Number of the sending party. The value MUST be a valid BPN. BPNA and BPNS are not allowed. Applicable constraints are defined in the corresponding standard"@en ; samm:characteristic :BpnCharacteristic ; samm:exampleValue "BPNL7588787849VQ" . :receiverBpn a samm:Property ; samm:preferredName "Receiver BPN"@en ; - samm:description """The Business Partner Number of the receiving party. - -The value MUST be a valid BPN. Applicable constraints are defined in the corresponding standard."""@en ; + samm:description "The Business Partner Number of the receiving party. The value MUST be a valid BPN. BPNA and BPNS are not allowed. Applicable constraints are defined in the corresponding standard."@en ; samm:characteristic :BpnCharacteristic ; samm:exampleValue "BPNL6666787765VQ" . :expectedResponseBy a samm:Property ; samm:preferredName "Expected Response By"@en ; - samm:description """Time zone aware timestamp holding the date and time by which the sending party expects a certain type of response from the receiving party. - -The meaning and interpretation of the fields's value are context-bound and MUST therefore be defined by any business domain or platform capability making use of it. - -The value MUST be formatted according to the ISO 8601 standard"""@en ; - samm:characteristic :Timestamp ; + samm:description "Time zone aware timestamp holding the date and time by which the sending party expects a certain type of response from the receiving party. The meaning and interpretation of the fields's value are context-bound and MUST therefore be defined by any business domain or platform capability making use of it. The value MUST be formatted according to the ISO 8601 standard"@en ; + samm:characteristic samm-c:Timestamp ; samm:exampleValue "2023-06-19T21:24:00+07:00"^^xsd:dateTimeStamp . :relatedMessageId a samm:Property ; @@ -93,9 +77,7 @@ The value MUST be formatted according to the ISO 8601 standard"""@en ; :version a samm:Property ; samm:preferredName "Version"@en ; - samm:description """The version of the standard defining the semantics and the structure of the message's header. - -The version number should follow the Semantic Versioning 2.0.0 specification"""@en ; + samm:description "The version of the standard defining the semantics and the structure of the message's header. The version number should follow the Semantic Versioning 2.0.0 specification."@en ; samm:characteristic :VersionCharacteristic ; samm:exampleValue "urn:samm:io.catenax.message_header:1.0.0" . @@ -109,11 +91,6 @@ The version number should follow the Semantic Versioning 2.0.0 specification"""@ samm:description "Defining a string value for the context"@en ; samm:dataType xsd:string . -:Timestamp a samm:Characteristic ; - samm:preferredName "Timestamp"@en ; - samm:description "Describes a Property which contains the date and time with an timezone."@en ; - samm:dataType xsd:dateTimeStamp . - :BpnCharacteristic a samm:Characteristic ; samm:preferredName "BPN Characteristic"@en ; samm:description "Characteristic for defining BPN values"@en ; From da972b96015d89324a7c731d5cf4433c7b3a0e8b Mon Sep 17 00:00:00 2001 From: Dominik Oeh Date: Mon, 24 Jul 2023 12:51:27 +0200 Subject: [PATCH 3/8] feat: add traits to specify semantic versioning and uuid characteristic --- .../1.0.0/MessageHeaderAspect.ttl | 27 +++++++++++++++++-- 1 file changed, 25 insertions(+), 2 deletions(-) diff --git a/io.catenax.message_header/1.0.0/MessageHeaderAspect.ttl b/io.catenax.message_header/1.0.0/MessageHeaderAspect.ttl index c76dae8b..bc43e0f9 100644 --- a/io.catenax.message_header/1.0.0/MessageHeaderAspect.ttl +++ b/io.catenax.message_header/1.0.0/MessageHeaderAspect.ttl @@ -49,7 +49,7 @@ String pattern of the value follows: --------- Date: Mon, 24 Jul 2023 12:58:43 +0200 Subject: [PATCH 4/8] chore: move message header model to new namespace --- .../1.0.0/MessageHeaderAspect.ttl | 16 +++++++++------- .../1.0.0/metadata.json | 0 .../RELEASE_NOTES.md | 0 3 files changed, 9 insertions(+), 7 deletions(-) rename {io.catenax.message_header => io.catenax.shared.message_header}/1.0.0/MessageHeaderAspect.ttl (93%) rename {io.catenax.message_header => io.catenax.shared.message_header}/1.0.0/metadata.json (100%) rename {io.catenax.message_header => io.catenax.shared.message_header}/RELEASE_NOTES.md (100%) diff --git a/io.catenax.message_header/1.0.0/MessageHeaderAspect.ttl b/io.catenax.shared.message_header/1.0.0/MessageHeaderAspect.ttl similarity index 93% rename from io.catenax.message_header/1.0.0/MessageHeaderAspect.ttl rename to io.catenax.shared.message_header/1.0.0/MessageHeaderAspect.ttl index bc43e0f9..64e10818 100644 --- a/io.catenax.message_header/1.0.0/MessageHeaderAspect.ttl +++ b/io.catenax.shared.message_header/1.0.0/MessageHeaderAspect.ttl @@ -5,7 +5,8 @@ @prefix rdf: . @prefix rdfs: . @prefix xsd: . -@prefix : . +@prefix : . +@prefix ext-header: . :MessageHeaderAspect a samm:Aspect ; samm:preferredName "Message Header Aspect"@en ; @@ -101,26 +102,27 @@ String pattern of the value follows: --- Date: Wed, 26 Jul 2023 08:40:41 +0200 Subject: [PATCH 5/8] chore: add license information --- .../1.0.0/MessageHeaderAspect.ttl | 23 ++++++++++++++++--- 1 file changed, 20 insertions(+), 3 deletions(-) diff --git a/io.catenax.shared.message_header/1.0.0/MessageHeaderAspect.ttl b/io.catenax.shared.message_header/1.0.0/MessageHeaderAspect.ttl index 64e10818..1b993729 100644 --- a/io.catenax.shared.message_header/1.0.0/MessageHeaderAspect.ttl +++ b/io.catenax.shared.message_header/1.0.0/MessageHeaderAspect.ttl @@ -1,3 +1,21 @@ +########################################################################################## +# Copyright (c) 2023 Bayerische Motoren Werke Aktiengesellschaft +# Copyright (c) 2023 Robert Bosch GmbH +# Copyright (c) 2023 Fraunhofer-Gesellschaft zur Förderung der angewandten Forschung e. V. +# Copyright (c) 2023 German Edge Cloud GmbH & Co. KG +# Copyright (c) 2023 SAP SE +# Copyright (c) 2023 Siemens AG +# +# See the NOTICE file(s) distributed with this work for additional +# information regarding copyright ownership. +# +# This work is made available under the terms of the +# Creative Commons Attribution 4.0 International (CC-BY-4.0) license, +# which is available at +# https://creativecommons.org/licenses/by/4.0/legalcode. +# +# SPDX-License-Identifier: CC-BY-4.0 +########################################################################################## @prefix samm: . @prefix samm-c: . @prefix samm-e: . @@ -6,18 +24,17 @@ @prefix rdfs: . @prefix xsd: . @prefix : . -@prefix ext-header: . :MessageHeaderAspect a samm:Aspect ; samm:preferredName "Message Header Aspect"@en ; - samm:description "Aspect model describing the message header, which must be included in every message"@en ; + samm:description "Aspect model describing the shared message header."@en ; samm:properties ( :header ) ; samm:operations ( ) ; samm:events ( ) . :header a samm:Property ; samm:preferredName "Header"@en ; - samm:description "Contains information common to all messages"@en ; + samm:description "Contains standardized attributes for message processing common across several use cases."@en ; samm:characteristic :HeaderCharacteristic . :HeaderCharacteristic a samm:Characteristic ; From ea80737d1ea020b78bd9f9341d1046cca269da9e Mon Sep 17 00:00:00 2001 From: Dominik Oeh Date: Wed, 26 Jul 2023 08:41:04 +0200 Subject: [PATCH 6/8] chore: add purpose of message header --- .../1.0.0/MessageHeaderAspect.ttl | 33 +++++++++---------- 1 file changed, 16 insertions(+), 17 deletions(-) diff --git a/io.catenax.shared.message_header/1.0.0/MessageHeaderAspect.ttl b/io.catenax.shared.message_header/1.0.0/MessageHeaderAspect.ttl index 1b993729..7c07ee38 100644 --- a/io.catenax.shared.message_header/1.0.0/MessageHeaderAspect.ttl +++ b/io.catenax.shared.message_header/1.0.0/MessageHeaderAspect.ttl @@ -44,7 +44,7 @@ :MessageHeader a samm:Entity ; samm:preferredName "Message Header"@en ; - samm:description "The header that must be included in every message."@en ; + samm:description "The Catena-X Message Header contains standardized attributes for message processing that are common across several use cases. It targets a minimal set of aspects that are needed for overall message handling, and not for the processing of the business related payload part. By standardizing the message header structure, we support a harmonized modelling approach and re-use of concepts. The message header originated from discussions on push notifications but has since then been abstracted for overall message handling – and does not only apply to notification anymore."@en ; samm:properties ( :messageId :context :sentDateTime :senderBpn :receiverBpn [ samm:property :expectedResponseBy; samm:optional true ] [ samm:property :relatedMessageId; samm:optional true ] :version ) . :messageId a samm:Property ; @@ -119,27 +119,26 @@ String pattern of the value follows: --- Date: Mon, 31 Jul 2023 08:42:22 +0200 Subject: [PATCH 7/8] feat: improve descriptions of context and version Improves descriptions of the message header's fields regarding the context and versioning --- .../1.0.0/MessageHeaderAspect.ttl | 14 ++++++++------ io.catenax.shared.message_header/RELEASE_NOTES.md | 2 +- 2 files changed, 9 insertions(+), 7 deletions(-) diff --git a/io.catenax.shared.message_header/1.0.0/MessageHeaderAspect.ttl b/io.catenax.shared.message_header/1.0.0/MessageHeaderAspect.ttl index 7c07ee38..0be215a2 100644 --- a/io.catenax.shared.message_header/1.0.0/MessageHeaderAspect.ttl +++ b/io.catenax.shared.message_header/1.0.0/MessageHeaderAspect.ttl @@ -56,12 +56,14 @@ :context a samm:Property ; samm:preferredName "Context"@en ; samm:description """Information about the context the message should be considered in. -Default: For Use Cases which need to validate against the Semantic Hub automatically. -Fallback: For Use Cases which do not use automatic validation. -In both cases: Versioning only refers to major versions. -String pattern of the value follows: ---"""@en ; +The value MUST consist of two parts: an identifier of the context (e.g. business domain, etc.) followed by a version number. +Both the identifier and the version number MUST correspond to the content of the message. +If the content of a message is described by an aspect model available in the Catena-X Semantic Hub, then the unique identifier of this semantic model (e.g. urn:samm:io.catenax.:1.x.x) MUST be used as a value of the context field. This is considered the default case. +In all other cases the value of the context field MUST follow the pattern --:<[major] version> (e.g. TRACE-QM-Alert:1.x.x). +Versioning only refers to major versions in both default and fallback cases. +Note: The version of the message's header is specified in the version field."""@en ; samm:characteristic :ContextCharacteristic ; - samm:exampleValue "urn:samm:io.catenax.:1.x.x" . + samm:exampleValue "urn:samm:io.catenax.:1.x.x" . :sentDateTime a samm:Property ; samm:preferredName "Sent Date Time"@en ; @@ -95,7 +97,7 @@ String pattern of the value follows: --- Date: Mon, 31 Jul 2023 13:26:48 +0200 Subject: [PATCH 8/8] feat: add reference to semver.org for version characteristic --- io.catenax.shared.message_header/1.0.0/MessageHeaderAspect.ttl | 1 + 1 file changed, 1 insertion(+) diff --git a/io.catenax.shared.message_header/1.0.0/MessageHeaderAspect.ttl b/io.catenax.shared.message_header/1.0.0/MessageHeaderAspect.ttl index 0be215a2..611b15d3 100644 --- a/io.catenax.shared.message_header/1.0.0/MessageHeaderAspect.ttl +++ b/io.catenax.shared.message_header/1.0.0/MessageHeaderAspect.ttl @@ -119,6 +119,7 @@ Note: The version of the message's header is specified in the version field."""@ :VersionCharacteristic a samm:Characteristic ; samm:preferredName "Version Characteristic"@en ; samm:description "Characteristic defining the value of version."@en ; + samm:see ; samm:dataType xsd:string . :UUIDv4 a samm-c:RegularExpressionConstraint ;