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..537fdff3 --- /dev/null +++ b/decisions/log/0035-unambiguous-createdupdated-attribute-descriptions.md @@ -0,0 +1,59 @@ +# 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 + +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 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: + +``` + + 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, 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, 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. + +``` + +## 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.