Merge pull request #46 from wbcsd/sine/adr28

ADR0028: deprecation of property `characterizationFactors` ; addition of new property `ipccCharacterizationFactorsSources`

decisions/log/0028-provide-clarity-on-characterization-factors.md

@@ -0,0 +1,54 @@
+# 28. Provide Clarity on Characterization Factors (AR5 and AR6)
+
+Date: 2024-01-16
+
+## Status
+
+Accepted
+
+## Context
+
+`characterizationFactors` is a mandatory property of the `CarbonFootprint` data type.
+It's data type is `String` and the value MUST be one of the following (see [4.2.2 Properties #characterizationFactors](https://wbcsd.github.io/tr/data-exchange-protocol/#element-attrdef-carbonfootprint-characterizationfactors)):
+- AR6
+  - for the Sixth Assessment Report of the Intergovernmental Panel on Climate Change (IPCC)
+- AR5
+  - for the Fifth Assessment Report of the IPCC
+
+However, some PCFs might be calculated with inputs that use both AR5 and AR6 as these can come from
+different sources (i.e., different actors in the supply chain). Since the IPCC will keep publishing reports (at an expected cadence of at least 5 years between reports), this problem tends to get worse in the future.
+
+In the context of the Methodology Working Group, PACT members have expressed a very strong
+preference for having the possibility of including more than one characterization factor per PCF.
+
+## Decision
+
+1. Change the definition of the `characterizationFactors` from:
+    > The IPCC version of the GWP characterization factors used in the calculation of the PCF (see [=Pathfinder Framework=]   Section 3.2.2). The value MUST be one of the following: [...]
+
+    to (roughly):
+    > **Deprecated**
+    >
+    > The IPCC version of the GWP characterization factors used **in the calculation of the largest relative share of the PCF** (see [=Pathfinder Framework=]   Section 3.2.2). The value MUST be one of the following: [...]
+    >
+    > [...]
+    >
+    > **Advisement: This property is deprecated and only kept to ensure backwards-compatibility. It does not replace the (also mandatory) property `characterizationFactorsSources`.**
+
+    (Please refer to the proposed changes to the technical specification for a more detailed and complete diff.)
+
+2. Add the new mandatory property `ipccCharacterizationFactorsSources` defined as a non-empty `Array` of `Strings` with the format `AR$VERSION$`, where `$VERSION$` stands for the IPCC report version number and MUST be an integer.
+
+### Rationale
+
+This proposal aims at providing a forward-looking change on characterization factors while preserving backwards-compatibility.
+
+Backwards-compatibility is preserved by keeping the `characterizationFactors` property (despite its becoming deprecated).
+
+It is forward-looking because future adaptations are unlikely to break backwards-compatibility. If a more fine-grained account of characterization factors use is ever desired, it can be included through optional properties of `CharacterizationFactorsSource`. If ever other sources become relevant (e.g., for specific industries) this too can be acommodated without the need for a breaking change.
+
+## Consequences
+
+1. This ADR introduces a minor change: since the `characterizationFactors` property is maintained, it is backwards compatible.
+2. Accordingly, the Technical Specifications version number must be updated from 2.1.x to 2.2.0.
+3. Host systems need to validate the new property `ipccCharacterizationFactorsSources` depending on the value of ProductFootprint's property `specsVersion`

spec/v2/index.bs

@@ -1,6 +1,6 @@
 <pre class='metadata'>
 Title: Technical Specifications for PCF Data Exchange
-Text Macro: VERSION 2.1.1-wip
+Text Macro: VERSION 2.2.0-20240312
 Shortname: data-exchange-protocol
 Level: 1
 Status: LD
@@ -496,14 +496,28 @@ Advisement:
         <td>String
         <td>M
         <td>
-            The IPCC version of the GWP characterization factors used in the calculation of the PCF (see [=Pathfinder Framework=] Section 3.2.2). The value MUST be one of the following:
+
+          Advisement: This property is DEPRECATED and only kept to ensure backwards-compatibility. It will be removed in version 3 of these Technical Specifications. It does not replace the (also mandatory) property <{CarbonFootprint/ipccCharacterizationFactorsSources}>.
+
+          The IPCC version of the GWP characterization factors used in the calculation of the PCF (see [=Pathfinder Framework=] Section 3.2.2). In case several characterization factors are used, indicate the earliest version used in your calculations, disregarding supplier provided PCFs. The value MUST be one of the following:
 
           : `AR6`
           :: for the Sixth Assessment Report of the Intergovernmental Panel on Climate Change (IPCC)
           : `AR5`
           :: for the Fifth Assessment Report of the IPCC.
+     <tr>
+        <td><dfn>ipccCharacterizationFactorsSources</dfn>
+        <td>Array of Strings
+        <td>M
+        <td>The characterization factors from one or more IPCC Assessment Reports used in the calculation of the PCF (see [=Pathfinder Framework=] Section 3.2.2).
+              It MUST be a non-empty set of strings with the format `AR$VERSION$`, where `$VERSION$` stands for the
+              IPCC report version number and MUST be an integer.
+
+          Example values:
+          <div class=example>["AR6"]</div>
+          <div class=example>["AR5", "AR6"]</div>
 
-          Advisement: The set of characterization factor identifiers will likely change in future revisions. It is recommended to account for this when implementing the validation of this property.
+          Advisement: Per the Framework, the latest available characterization factor version shall be used, i.e., `["AR6"]`. In the event this is not possible, include the set of all characterization factors used.
       <tr>
         <td><dfn>crossSectoralStandardsUsed</dfn> : [=CrossSectoralStandardSet=]
         <td>Array
@@ -1387,7 +1401,6 @@ Example JSON string value:
 ```
 </div>
 
-
 # Product Footprint Lifecycle # {#lifecycle}
 
 ## Introduction ## {#lifecycle-intro}
@@ -2295,6 +2308,13 @@ path: LICENSE.md
 
 # Appendix B: Changelog # {#changelog}
 
+## Version 2.2.0-20240312 (Mar 12, 2024) ## {#changelog-2.2.0-20240312}
+
+Summary of changes:
+
+1. deprecation of the <{CarbonFootprint/characterizationFactors}> property
+2. addition of a new <{CarbonFootprint/ipccCharacterizationFactorsSources}> property
+
 ## Version 2.1.0 (Dec 07, 2023) ## {#changelog-2.1.0}
 
 This version introduces additional mandatory functionality: