Merge pull request #98 from wbcsd/pact/adr39

ADR-0039 Consistent typing of real numbers

decisions/log/0039-consistent-typing-real-numbers.md

@@ -0,0 +1,72 @@
+# 39. Consistent typing of real numbers
+
+Date: 2024-09-23
+
+## Context
+
+As the PACT data model evolved, numerous properties have been added, some of them denoting real numbers, like percentages and ratings (in contrast to integers which are always whole numbers). 
+
+As there
+is a certain amount of ambiguity in the JSON format regarding real numbers, this has 
+resulted in several properties having different ways of representing numbers. This
+can lead to confusion for implementors and users of the data. 
+
+This proposal aims to remedy that by uniformly typing these numbers and adding 
+guidelines for future expansion of the specs.
+
+## Background
+
+The JSON data format does not specify any precision for numbers. The representation of 
+these have been delegated to implementors. As a result, JSON parsers in different programming languages
+thus have several ways of interpreting and storing real numbers. Although rare, in worst case, this could result in (some) data loss.
+
+In order not to be dependent on technical implementations, PACT has choosen to represent 
+numeric emission data (carbon footprint emissions) as decimal numbers formatted as strings. 
+
+Example:
+
+    { 
+        "fossilGhgEmissions": "12345.6789"
+    }
+
+This way no precision is lost, although the burden of interpreting these numbers is 
+now relegated to the implementors of the PACT API. This is, however, in most cases 
+trivial and most programming languages have support for Decimal type numbers
+specially purposed for scientific and financial calculations.
+
+## Proposal
+
+Based on discussion both with the community (Takuro Okada of NRI) and internally, we propose the following for consultation and revision.
+
+- Change the type of the following attributes (properties) from Number to "Decimal" (string):
+  - `pcf.exemptedEmissionsPercent`
+  - `pcf.primaryDataShare`    
+  - `pcf.dqi.coveragePercent`     
+  - `pcf.dqi.technologicalDQR`    
+  - `pcf.dqi.temporalDQR`         
+  - `pcf.dqi.geographicalDQR`     
+  - `pcf.dqi.completenessDQR`    
+  - `pcf.dqi.reliabilityDQR`      
+
+- Note: property `version` will stay a Number as it will always be an integer.
+
+- Add a guideline to the Tech Specs, aiding the addition of future properties, as well
+as guiding the types in data extensions:
+    - For integers (*and only* for integers) use the JSON **Number** type and include the `integer` format specifier in the OpenAPI schema.
+
+            { counter: 1 }
+
+    - For real numbers *ALWAYS* use the **Decimal** type: an arbitrary sized number, formatted as a string, with a '.' (dot) as decimal point, *without* any thousands separators. 
+
+            { temperature: "12.3" }
+
+## Consequences
+
+As this would break backwards compatibility with version 2.x these changes should - if accepted - be included from version 3 upwards.
+
+## Status
+
+Proposed 
+Presented in the Tech Working Group meeting of Sept 25, 2024. 
+Feedback to be collected.
+

spec/v3/examples/get-footprint-response.json

@@ -57,19 +57,19 @@
           "version": "3.1"
         }
       ],
-      "exemptedEmissionsPercent": 0,
+      "exemptedEmissionsPercent": "0",
       "exemptedEmissionsDescription": "",
       "packagingEmissionsIncluded": false,
       "allocationRulesDescription": "Using mass allocation following the product specific rule as per PACT Framework decision-making tree",
       "uncertaintyAssessmentDescription": "A model of corn production is involved in predicting emissions from the production of the corn feedstock. Emissions of N2O due to application of nitrogen fertilizers are based on a linear modeling of interactions of the fertilizer with the soil and plant systems. As these interactions are more complicated than the model assumes, there is uncertainty regarding the emissions resulting from this model",
-      "primaryDataShare": 12.9,
+      "primaryDataShare": "12.9",
       "dqi": {
-        "coveragePercent": 78,
-        "technologicalDQR": 1.6,
-        "temporalDQR": 2.6,
-        "geographicalDQR": 1.8,
-        "completenessDQR": 1.7,
-        "reliabilityDQR": 2.1
+        "coveragePercent": "78",
+        "technologicalDQR": "1.6",
+        "temporalDQR": "2.6",
+        "geographicalDQR": "1.8",
+        "completenessDQR": "1.7",
+        "reliabilityDQR": "2.1"
       },
       "assurance": {
         "assurance": false,

spec/v3/examples/invalid-response-all-properties.json

@@ -64,20 +64,20 @@
                         "version": "1.2.3"
                     }
                 ],
-                "exemptedEmissionsPercent": 0.0,
+                "exemptedEmissionsPercent": "0.0",
                 "exemptedEmissionsDescription": "",
                 "packagingEmissionsIncluded": true,
                 "packagingGhgEmissions": "2.123",
                 "allocationRulesDescription": "Allocation rules description",
                 "uncertaintyAssessmentDescription": "Uncertainty assessment description",
-                "primaryDataShare": 10.4,
+                "primaryDataShare": "10.4",
                 "dqi": {
-                    "coveragePercent": 100,
-                    "technologicalDQR": 1.13,
-                    "temporalDQR": 2.57,
-                    "geographicalDQR": 1,
-                    "completenessDQR": 2.6,
-                    "reliabilityDQR": 1.79
+                    "coveragePercent": "100",
+                    "technologicalDQR": "1.13",
+                    "temporalDQR": "2.57",
+                    "geographicalDQR": "1",
+                    "completenessDQR": "2.6",
+                    "reliabilityDQR": "1.79"
                 },
                 "assurance": {
                     "coverage": "product line",

spec/v3/examples/list-footprints-response.json

@@ -58,19 +58,19 @@
             "version": "3.1"
           }
         ],
-        "exemptedEmissionsPercent": 0,
+        "exemptedEmissionsPercent": "0",
         "exemptedEmissionsDescription": "",
         "packagingEmissionsIncluded": false,
         "allocationRulesDescription": "Using mass allocation following the product specific rule as per PACT Framework decision-making tree",
         "uncertaintyAssessmentDescription": "A model of corn production is involved in predicting emissions from the production of the corn feedstock. Emissions of N2O due to application of nitrogen fertilizers are based on a linear modeling of interactions of the fertilizer with the soil and plant systems. As these interactions are more complicated than the model assumes, there is uncertainty regarding the emissions resulting from this model",
-        "primaryDataShare": 12.9,
+        "primaryDataShare": "12.9",
         "dqi": {
-          "coveragePercent": 78,
-          "technologicalDQR": 1.6,
-          "temporalDQR": 2.6,
-          "geographicalDQR": 1.8,
-          "completenessDQR": 1.7,
-          "reliabilityDQR": 2.1
+          "coveragePercent": "78",
+          "technologicalDQR": "1.6",
+          "temporalDQR": "2.6",
+          "geographicalDQR": "1.8",
+          "completenessDQR": "1.7",
+          "reliabilityDQR": "2.1"
         },
         "assurance": {
           "assurance": false,

spec/v3/examples/pf-response-event.json

@@ -65,19 +65,19 @@
               "version": "3.1"
             }
           ],
-          "exemptedEmissionsPercent": 0,
+          "exemptedEmissionsPercent": "0",
           "exemptedEmissionsDescription": "",
           "packagingEmissionsIncluded": false,
           "allocationRulesDescription": "Using mass allocation following the product specific rule as per PACT Framework decision-making tree",
           "uncertaintyAssessmentDescription": "A model of corn production is involved in predicting emissions from the production of the corn feedstock. Emissions of N2O due to application of nitrogen fertilizers are based on a linear modeling of interactions of the fertilizer with the soil and plant systems. As these interactions are more complicated than the model assumes, there is uncertainty regarding the emissions resulting from this model",
-          "primaryDataShare": 12.9,
+          "primaryDataShare": "12.9",
           "dqi": {
-            "coveragePercent": 78,
-            "technologicalDQR": 1.6,
-            "temporalDQR": 2.6,
-            "geographicalDQR": 1.8,
-            "completenessDQR": 1.7,
-            "reliabilityDQR": 2.1
+            "coveragePercent": "78",
+            "technologicalDQR": "1.6",
+            "temporalDQR": "2.6",
+            "geographicalDQR": "1.8",
+            "completenessDQR": "1.7",
+            "reliabilityDQR": "2.1"
           },
           "assurance": {
             "assurance": false,

spec/v3/index.bs

@@ -788,13 +788,12 @@ The mass (in kg) of the product per the provided <{CarbonFootprint/declaredUnit|
         If no secondary data is used, this property MUST BE `undefined`.
       <tr>
         <td><dfn>exemptedEmissionsPercent</dfn>
-        <td>Number
+        <td>[=Decimal=]
         <td>M
         <td>
+          The percentage of emissions excluded from PCF, expressed as a decimal number. See [=PACT Methodology=].
 
-            Advisement: The upper boundary of this property (currently `5`) will be removed in version 3 of the Technical Specifications.
-
-            The Percentage of emissions excluded from PCF, expressed as a decimal number between `0.0` and `5` including. See [=PACT Methodology=].
+          Advisement: [=Decimal=] in 3.0, was Number in 2.x
       <tr>
         <td><dfn>exemptedEmissionsDescription</dfn>
         <td>String
@@ -828,15 +827,17 @@ The mass (in kg) of the product per the provided <{CarbonFootprint/declaredUnit|
         <td>O
             <td>If present, the results, key drivers, and a short qualitative description of the uncertainty assessment.
       <tr>
-        <td><dfn>primaryDataShare</dfn> : [=Percent=]
-        <td>Number
+        <td><dfn>primaryDataShare</dfn>
+        <td>[=Decimal=]
         <td>O*
         <td>
           The share of primary data in percent. See the [=PACT Methodology=] Sections 4.2.1 and 4.2.2, Appendix B.
 
           For reference periods ending before the beginning of year 2025, at least property <{CarbonFootprint/primaryDataShare}> or propery <{CarbonFootprint/dqi}> MUST be defined.
 
           For reference periods including the beginning of year 2025 or after, this property MUST be defined.
+
+          Advisement: [=Decimal=] in 3.0, was Number in 2.x
       <tr>
         <td><dfn>dqi</dfn> : <{DataQualityIndicators}>
         <td>Object
@@ -864,6 +865,8 @@ Data type `DataQualityIndicators` contains the quantitative data quality indicat
 
 Each property is optional until the reference period includes the beginning of calendar year 2025, or later, when all properties MUST be defined.
 
+Advisement: Starting version 3.0 the properties in DataQualityIndicators are typed [=Decimal=], instead of `Number`.
+
 The following properties are defined for data type <{DataQualityIndicators}>:
 
 <figure id="pf-dataqualityindicators-properties-table" dfn-type="element-attr" dfn-for="DataQualityIndicators">
@@ -875,55 +878,67 @@ The following properties are defined for data type <{DataQualityIndicators}>:
         <th>Specification
     <tbody>
       <tr>
-        <td><dfn>coveragePercent</dfn> : [=Percent=]
-        <td>Number
+        <td><dfn>coveragePercent</dfn>
+        <td>Decimal
         <td>
           Percentage of PCF included in the data quality assessment based on the `>5%` emissions threshold.
+
+          Advisement: [=Decimal=] in 3.0, was Number in 2.x
       <tr>
         <td><dfn>technologicalDQR</dfn>
-        <td>Number
+        <td>Decimal
         <td>
           Quantitative data quality rating (DQR) based on the data quality matrix (See [=PACT Methodology=] Table 9),
           scoring the technological representativeness of the sources used for PCF calculation based on
           weighted average of all inputs representing >5% of PCF emissions.
 
           The value MUST be a [=decimal=] between `1` and `3` including.
+
+          Advisement: [=Decimal=] in 3.0, was Number in 2.x
       <tr>
         <td><dfn>temporalDQR</dfn>
-        <td>Number
+        <td>Decimal
         <td>
           Quantitative data quality rating (DQR) based on the data quality matrix (Table 9),
           scoring the temporal representativeness of the sources used for PCF calculation based on
           weighted average of all inputs representing >5% of PCF emissions.
 
           The value MUST be between `1` and `3` inclusive.
+
+          Advisement: [=Decimal=] in 3.0, was Number in 2.x
       <tr>
         <td><dfn>geographicalDQR</dfn>
-        <td>Number
+        <td>Decimal
         <td>
           Quantitative data quality rating (DQR) based on the data quality matrix (Table 9),
           scoring the geographical representativeness of the sources used for PCF calculation
           based on weighted average of all inputs representing >5% of PCF emissions.
 
           The value MUST be between `1` and `3` inclusive.
+
+          Advisement: [=Decimal=] in 3.0, was Number in 2.x
       <tr>
         <td><dfn>completenessDQR</dfn>
-        <td>Number
+        <td>Decimal
         <td>
           Quantitative data quality rating (DQR) based on the data quality matrix (Table 9),
           scoring the completeness of the data collected for PCF calculation based on
           weighted average of all inputs representing >5% of PCF emissions.
 
           The value MUST be between `1` and `3` inclusive.
+
+          Advisement: [=Decimal=] in 3.0, was Number in 2.x
       <tr>
         <td><dfn>reliabilityDQR</dfn>
-        <td>Number
+        <td>Decimal
         <td>
           Quantitative data quality rating (DQR) based on the data quality matrix (Table 9),
           scoring the reliability of the data collected for PCF calculation based on
           weighted average of all inputs representing >5% of PCF emissions.
 
           The value MUST be between `1` and `3` inclusive.
+
+          Advisement: [=Decimal=] in 3.0, was Number in 2.x
     </table>
   <figcaption>Properties of data type DataQualityIndicators</figcaption>
 </figure>
@@ -932,11 +947,11 @@ The following properties are defined for data type <{DataQualityIndicators}>:
   Example value for the case that all DQIs are known but no coverage after exemption assessment performed:
   <pre highlight=json>
   {
-    "technologicalDQR": 2.0,
-    "temporalDQR": 2.0,
-    "geographicalDQR": 2.0,
-    "completenessDQR": 2.0,
-    "reliabilityDQR": 2.0
+    "technologicalDQR": "2.0",
+    "temporalDQR": "2.0",
+    "geographicalDQR": "2.0",
+    "completenessDQR": "2.0",
+    "reliabilityDQR": "2.0"
   }
   </pre>
 </div>
@@ -1404,41 +1419,6 @@ Each [=String=] MUST be encoded as a JSON String.
 
 
 
-## Data Type: <dfn>Percent</dfn> ## {#dt-percent}
-
-A Decimal number in the range of and including `0` and `100`.
-
-Example values:
-<div class=example>
-    - `100`
-    - `23.0`
-    - `7.183924`
-    - `0.0`
-</div>
-
-### JSON Representation ### {#dt-percent-json}
-
-Each Percent MUST be encoded in IEEE-754 [double-precision floating-point format](https://en.wikipedia.org/wiki/Double-precision_floating-point_format) as a JSON number.
-
-
-
-## Data Type: <dfn element>StrictlyPositiveDecimal</dfn> ## {#dt-strictlypositivedecimal}
-
-A positive, non-zero Decimal.
-
-Example values:
-<div class=example>
-    - 0.123
-    - 1000
-    - 42.102340
-</div>
-
-### JSON Representation ### {#dt-strictlypositivedecimal-json}
-
-See [[[#dt-decimal-json]]].
-
-
-
 ## Data Type: <dfn>DateTime</dfn> ## {#dt-datetime}
 
 Each DateTime MUST be a date and time string conforming to ISO 8601. The timezone MUST be UTC.
@@ -1485,6 +1465,7 @@ Example values:
 Each Decimal MUST be encoded as a JSON String.
 
 
+
 ## Data Type: <dfn>PfId</dfn> ## {#dt-pfid}
 
 A PfId MUST be a UUID v4 as specified in [[!RFC9562]].
@@ -2762,6 +2743,7 @@ path: ../../LICENSE.md
 
 # Appendix B: Changelog # {#changelog}
 
+
 ## Version 3.0.0-20241212 (Dec 12, 2024) ## {#changelog-3.0.0}
 
 Summary of changes:
@@ -2773,6 +2755,8 @@ Summary of changes:
 6. Deprecation of property <{CarbonFootprint/characterizationFactors}> (ADR28)
 7. Removal of `crossSectoralStandardsUsed` which has been deprecated in 2.3 and is now superseeded by extensible crossSectoralStandards (ADR32).
 8. Assurance/<{Assurance/providername}> now optional, after being mistakenly made mandatory in version 2.x
+9. Consistent Decimal typing for all fractional numbers (ADR39). The data type of the following fields has been changed from Number to Decimal: `primaryDataShare`, `exemptedEmissionsPercent`, `coveragePercent`, `technologicalDQR`, `temporalDQR`, `geographicalDQR`, `completenessDQR`, `reliabilityDQR`
+
 
 ## Version 2.3.0 (Oct 24, 2024) ## {#changelog-2.3.0}