ADR0028: deprecation of property characterizationFactors ; addition of new property characterizationFactorsSources

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

@@ -0,0 +1,55 @@
+# 28. Provide Clarity on Characterization Factors (AR5 and AR6)
+
+Date: 2024-01-16
+
+## Status
+
+Proposed
+
+## 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, 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 `characterizationFactorsSources` with the new data type `CharacterizationFactorsSources`, defined as a non-empty `Array` of `CharacterizationFactorsSource`. The new data type `CharacterizationFactorsSource` is defined as an `Object` with the mandatory fields `"name"` and `"version"`, both of which are non-empty `Strings`. The value of the `"name"` field SHOULD be `"IPCC Assessment Report"` and the version SHOULD be either `"5"` or `"6"`.
+
+### 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 as future adaptations will hardly 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 `characterizationFactorsSources` depending on the value of ProductFootprint's property `specsVersion`

spec/v2/index.bs

@@ -493,14 +493,21 @@ 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:
+          **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:
 
           : `AR6`
           :: for the Sixth Assessment Report of the Intergovernmental Panel on Climate Change (IPCC)
           : `AR5`
           :: for the Fifth Assessment Report of the IPCC.
 
-          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: This property is deprecated and only kept to ensure backwards-compatibility. It will be removed on version 3 of these Technical Specifications. It does not replace the (also mandatory) property <{CarbonFootprint/characterizationFactorsSources}>.
+      <tr>
+        <td><dfn>characterizationFactorsSources</dfn>  : [=CharacterizationFactorsSourcesSet=]
+        <td>Array
+        <td>M
+        <td>The set of characterization factors used in the calculation of the PCF (see [=Pathfinder Framework=] Section 3.2.2). The value MUST be a [=CharacterizationFactorsSourcesSet=].
       <tr>
         <td><dfn>crossSectoralStandardsUsed</dfn> : [=CrossSectoralStandardSet=]
         <td>Array
@@ -1382,6 +1389,46 @@ Example JSON string value:
 ```
 </div>
 
+## Data Type: <dfn>CharacterizationFactorsSourcesSet</dfn> ## {#dt-characterizationfactorssourcesset}
+
+A set of 1 or more <{CharacterizationFactorsSource|Characterization Factors Sources}>.
+
+### JSON Representation ### {#dt-characterizationfactorssourcesset-json}
+
+As an array of objects, with each object conforming to the JSON representation of <{CharacterizationFactorsSource}>.
+
+## Data Type: <dfn element>CharacterizationFactorsSource</dfn> ## {#dt-characterizationfactorssource}
+
+A `CharacterizationFactorsSource` references a source of the characterization factors used in the calculation of the <{CarbonFootprint}> (see [=Pathfinder Framework=] Section 3.2.2).
+
+### Properties ### {#dt-characterizationfactorssource-properties}
+
+<dl dfn-type="element-attr" dfn-for="CharacterizationFactorsSource">
+: <dfn>name</dfn> (mandatory, data type: [=NonEmptyString=]) :: The non-empty name of the
+characterization factors source. Presently, the value SHOULD be `"IPCC Assessment Report"`,
+referring to the characterization factors (100-year GWP, including carbon feedbacks) derived from
+the IPCC Assessment Report publication.
+
+: <dfn>version</dfn> (mandatory, data type: [=NonEmptyString=]) :: The non-empty version of the
+characterization factors source. Presently, the value SHOULD be either `"5"` or `"6"`, referring to
+the 5th (AR5) and 6th (AR6) IPCC Assessment Reports, respectively.
+</dl>
+
+<div class=example>
+Example encoding of a <{CharacterizationFactorsSource}> in JSON:
+
+```json
+{
+  "name": "IPCC Assessment Report",
+  "version": "6"
+}
+```
+</div>
+
+
+### JSON Representation ### {#dt-characterizationfactorssource-json}
+
+Each <{CharacterizationFactorsSource}> MUST be encoded as a JSON object.
 
 # Product Footprint Lifecycle # {#lifecycle}
 
@@ -2240,7 +2287,7 @@ date: Mon, 23 May 2022 19:33:16 GMT
 content-type: application/json
 content-length: 1831
 server: Pathfinder
-link: &lt;https://api.pathfinder.sine.dev/2/footprints?limit=10&amp;offset=10&gt;; rel="next"
+link: &lt;https://api.pathfinder.sine.dev/2/footprints?limit=10&offset=10&gt;; rel="next"
 </pre>
 
 Example response body: