From 842a5cd078f8fc5c6cc3329e0d6f1742ea1a9671 Mon Sep 17 00:00:00 2001 From: Beth Hadley Date: Tue, 6 Aug 2024 12:32:43 +0200 Subject: [PATCH 1/4] Create 0035-unambiguous-createdupdated-attribute-descriptions.md ADR to address ambiguous created and update attribute descriptions --- ...s-createdupdated-attribute-descriptions.md | 58 +++++++++++++++++++ 1 file changed, 58 insertions(+) create mode 100644 decisions/log/0035-unambiguous-createdupdated-attribute-descriptions.md diff --git a/decisions/log/0035-unambiguous-createdupdated-attribute-descriptions.md b/decisions/log/0035-unambiguous-createdupdated-attribute-descriptions.md new file mode 100644 index 00000000..821cccee --- /dev/null +++ b/decisions/log/0035-unambiguous-createdupdated-attribute-descriptions.md @@ -0,0 +1,58 @@ +# 35. Unambiguous created & updated attribute description + +Date: Aug 6, 2024 + +Author: Beth Hadley + +## Status + +Proposed +- Discussed with initiatives (TfS, CX) and internally +- To be presented to Tech Working Group August 7, 2024 + +## Context + +### Business Context +The attributes `created` and `updated` in the PACT Tech Specs are defined in an ambiguous way. The current description simply defines "created" as "the timestamp of the creation of the ProductFootprint" which could be interpreted a number of ways functionally: +- When the PCF calculation began +- When the PCF calculate ended +- When the PCF calculation was entered into the software +- When the PCF was made available +- When the PCF was issued (i.e. declared, independent of when or if it has been shared) + +Or, alternatively, the meaning could be purely technical without any functional interpretation regarding the PCF itself: +- When the data record was written into the system (i.e. a record created in a database, etc.) + +This ambiguity has resulted in confusion and misaligned interpretation of this field. TfS for example has interpreted `created` as the "Date of Issue", whereas (some) solution providers have interpreted `created` as the time stamp of The PCF record being created in their system (without functional meaning necessarily). + +When SAP first raised this question to PACT (October 2023) we learned from the early editors of the PACT Tech Specs that the original intention of the attribute was to leave the interpretation ambiguous. We then validated with the Tech Working Group the need to define the attribute unambiguously, and the community agreed with resounding consensus. We decided to pause however on reaching consensus on the definition until we could address all 6 datetime attributes holistically, to ensure the definition agreed does not overlap with the other datetime attributes. +Screenshot 2024-08-06 at 11 59 56 + +Screenshot 2024-08-06 at 12 17 08 + +## Proposal + +Given the above context, we have now clarified that the intention of the `created` and `updated` attributes are strictly technical; to enable systems to maintain records internally, and to give indication to receiving systems regarding the data records. The attributes are not intended to have any functional interpretation, and further are standard attributes in any data model for data exchange. With this context, we are now able to provide unambiguous definitions of the attributes. + +Therefore, we propose to clarify the ambiguity by updating the attribute descriptions accordingly: + +``` + + created : [=DateTime=] + String + M + A ProductFootprint MUST include the property created with value the timestamp of the creation of the ProductFootprint record in the system. No corresponding functional meaning is necessarily attributed to the record creation in the system. The timestamp MUST be in UTC. + + + updated : [=DateTime=] + String + O + A ProductFootprint SHOULD include the property updated with value the timestamp of the update of the ProductFootprint record in the system. A ProductFootprint MUST NOT include this property if an update of the record has never been performed. No corresponding functional meaning is necessarily attributed to the record update in the system. The timestamp MUST be in UTC. + +``` + +## Consequences + +1. The above update is a semantic clarification and does not cause a backwards breaking change, therefore the update can be made in Technical Specification V2.3 +2. Solution Providers who may have interpreted the attributes differently should take note of this update and update their implementations accordingly. +3. Initiatives (TfS, CX) have been part of this discussion and decision and will likewise take this update into consideration as we continue to work towards harmonization. From 4f267fb078601f0ca8a270dedef16d8d15192724 Mon Sep 17 00:00:00 2001 From: Beth Hadley Date: Tue, 6 Aug 2024 13:03:42 +0200 Subject: [PATCH 2/4] Update 0035-unambiguous-createdupdated-attribute-descriptions.md Addition of link to PACT Decision Log --- .../0035-unambiguous-createdupdated-attribute-descriptions.md | 1 + 1 file changed, 1 insertion(+) diff --git a/decisions/log/0035-unambiguous-createdupdated-attribute-descriptions.md b/decisions/log/0035-unambiguous-createdupdated-attribute-descriptions.md index 821cccee..50599602 100644 --- a/decisions/log/0035-unambiguous-createdupdated-attribute-descriptions.md +++ b/decisions/log/0035-unambiguous-createdupdated-attribute-descriptions.md @@ -30,6 +30,7 @@ When SAP first raised this question to PACT (October 2023) we learned from the e Screenshot 2024-08-06 at 12 17 08 +PACT Decision Log Entry for this feedback: https://flat-dollar-c04.notion.site/Clarification-to-definition-of-tech-spec-attribute-created-updated-65455b3d9cb24329b2655d0ed3f8c7f7?pvs=74 ## Proposal Given the above context, we have now clarified that the intention of the `created` and `updated` attributes are strictly technical; to enable systems to maintain records internally, and to give indication to receiving systems regarding the data records. The attributes are not intended to have any functional interpretation, and further are standard attributes in any data model for data exchange. With this context, we are now able to provide unambiguous definitions of the attributes. From 534d6ead10e5947aee993f20644f74528c5c8fda Mon Sep 17 00:00:00 2001 From: Beth Hadley Date: Tue, 6 Aug 2024 13:42:47 +0200 Subject: [PATCH 3/4] Update 0035-unambiguous-createdupdated-attribute-descriptions.md --- .../0035-unambiguous-createdupdated-attribute-descriptions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/decisions/log/0035-unambiguous-createdupdated-attribute-descriptions.md b/decisions/log/0035-unambiguous-createdupdated-attribute-descriptions.md index 50599602..733fe0db 100644 --- a/decisions/log/0035-unambiguous-createdupdated-attribute-descriptions.md +++ b/decisions/log/0035-unambiguous-createdupdated-attribute-descriptions.md @@ -33,7 +33,7 @@ When SAP first raised this question to PACT (October 2023) we learned from the e PACT Decision Log Entry for this feedback: https://flat-dollar-c04.notion.site/Clarification-to-definition-of-tech-spec-attribute-created-updated-65455b3d9cb24329b2655d0ed3f8c7f7?pvs=74 ## Proposal -Given the above context, we have now clarified that the intention of the `created` and `updated` attributes are strictly technical; to enable systems to maintain records internally, and to give indication to receiving systems regarding the data records. The attributes are not intended to have any functional interpretation, and further are standard attributes in any data model for data exchange. With this context, we are now able to provide unambiguous definitions of the attributes. +Given the above context, we have now clarified that the intention of the `created` and `updated` attributes is strictly technical; to enable systems to maintain records internally, and to give indication to receiving systems regarding the data records. The attributes are not intended to have any functional interpretation, and further are standard attributes in any data model for data exchange. With this context, we are now able to provide unambiguous definitions of the attributes. Therefore, we propose to clarify the ambiguity by updating the attribute descriptions accordingly: From 816f4601683b466061e0addd527a9bc4947b07d9 Mon Sep 17 00:00:00 2001 From: Beth Hadley Date: Tue, 6 Aug 2024 18:47:08 +0200 Subject: [PATCH 4/4] Update 0035-unambiguous-createdupdated-attribute-descriptions.md Small update to description, based on feedback from PACT Methodology --- .../0035-unambiguous-createdupdated-attribute-descriptions.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/decisions/log/0035-unambiguous-createdupdated-attribute-descriptions.md b/decisions/log/0035-unambiguous-createdupdated-attribute-descriptions.md index 733fe0db..537fdff3 100644 --- a/decisions/log/0035-unambiguous-createdupdated-attribute-descriptions.md +++ b/decisions/log/0035-unambiguous-createdupdated-attribute-descriptions.md @@ -42,13 +42,13 @@ Therefore, we propose to clarify the ambiguity by updating the attribute descrip created : [=DateTime=] String M - A ProductFootprint MUST include the property created with value the timestamp of the creation of the ProductFootprint record in the system. No corresponding functional meaning is necessarily attributed to the record creation in the system. The timestamp MUST be in UTC. + A ProductFootprint MUST include the property created with value the timestamp of the creation of the ProductFootprint record in the system, potentially independently from the PCF calculation, creation, issue, or sharing. This attribute is a technical system attribute, for maintaining records systematically within and between systems. The timestamp MUST be in UTC. updated : [=DateTime=] String O - A ProductFootprint SHOULD include the property updated with value the timestamp of the update of the ProductFootprint record in the system. A ProductFootprint MUST NOT include this property if an update of the record has never been performed. No corresponding functional meaning is necessarily attributed to the record update in the system. The timestamp MUST be in UTC. + A ProductFootprint SHOULD include the property updated with value the timestamp of the update of the ProductFootprint record in the system, potentially independently from when the PCF itself was updated. This attribute is a technical system attribute, for maintaining records systematically within and between systems. A ProductFootprint MUST NOT include this property if an update of the record has never been performed. The timestamp MUST be in UTC. ```