Technical Specification for Data Model Extensions

Living Document,

This version:
https://wbcsd.github.io/data-model-extensions/spec/
Feedback:
pact@wbcsd.org with subject line “[usecase-003-specs] … message topic …”
Issue Tracking:
GitHub
Editor:
Beth Hadley (WBCSD)
Former Editor:
Martin Pompéry (SINE Foundation)

Abstract

This draft document specifies data model extensions and their representation within a ProductFootprint document in accordance with the Guidance and Criteria for Pathfinder Data Model Extensions.

1. Introduction

This document specifies data model extensions and their representation within a ProductFootprint document of the Pathfinder Data Model.

The foundation for extensibility is the Data Model Extension Guidance (see [EXTENSIONS-GUIDANCE]).

1.1. Background

Companies need to exchange emission data at product level in order to understand the carbon footprint of their products, to comply with regulations, or to improve the environmental and social footprint of their products.

One realization of this is the Pathfinder Data Model which has its methodological roots in the Pathfinder Framework (see [PATHFINDER-FRAMEWORK]).

By design, this methodology gives guidance for footprint information shared by a multitude of industries and sectors. The Framework itself and the data attributes defined in it are industry-agnostic.

Additional attributes of high specificity, for instance for certain sectors or activities related to a category of products or services, have a high utility value for the recipients of product footprint data. Since they are specific, they are out of the scope of the Pathfinder Framework.

In order to enable the exchange of such additional attributes, this document specifies data model extensions (§ 4 Data Model Extension) and the resulting digital representation of data model extensions (§ 5 JSON Representation of a Data Model Extension) within the Pathfinder Network data model (§ 6 Encoding and Integration of Extensions into the Pathfinder Data Model).

2. Definitions

Pathfinder Data Model

The ProductFootprint data model and definitions from [DATA-EXCHANGE-PROTOCOL]

PACT Data Exchange Protocol

See technical specifications from [DATA-EXCHANGE-PROTOCOL]

Host System

A system running software that is conforming to the PACT Data Exchange Protocol. See the same specification for further details.

ProductFootprint

The footprint document related to a product, as defined in [DATA-EXCHANGE-PROTOCOL].

3. Example Business Case and Data Model Extension

Non-normative.

A logistics-sector initiative decided to use the Pathfinder data model. In order to enable GHG carbon emission accounting and reporting on this matter, they define an extension. The extension defines attributes related to the forthcoming ISO 14083, covering shipments and consignments.

Example representation (§ 5 JSON Representation of a Data Model Extension) of the exemplary logistics data model extension encoded in JSON:

{
  "specVersion": "2.0.0",
  "dataSchema": "https://catalog.carbon-transparency.com/shipment/1.0.0/schema.json",
  "data": {
    "shipmentId": "1234567890",
    "consignmentId": "abcdefghi",
    "shipmentType": "PICKUP",
    "weight": 10,
    "transportChainElementId": "ABCDEFGHI"
  }
}

The property dataSchema references the § 4.3 Extension Schema File.

The property specVersion is set to 2.0.0, referencing the version of this specification.

4. Data Model Extension

4.1. Purpose and Audience of Data Model Extensions

Non-normative.

The purpose of a data model extension is to increase the utility of the Pathfinder data model for users wanting to exchange product-level emissions data.

The audience of data model extensions and their related documents are:

4.2. Definition

A data model extension consists of the following documents:

  1. The Extension Schema file that defines the data model extension (§ 4.3 Extension Schema File)

  2. The Extension Documentation for users and implementers of the data model extension (§ 4.4 Extension Documentation)

4.3. Extension Schema File

Every extension MUST define a valid JSON Schema document according to the JSON Schema specification. The extension schema file defines the data encoding and syntactical data validation details.

Authors of extension schema definitions SHOULD attempt to add as many validation rules as possible such that data validation can be automated as much as possible.

Extension schemas SHOULD be defined in a way to make illegal extension representations unrepresentable.

Additional details which are not representable in JSON Schema such as data semantics or validation rules, MUST be defined in the extension documentation (§ 4.4 Extension Documentation).

4.4. Extension Documentation

The extension documentation is a human-readable document that describes the extension in detail. Extension document MUST be written in English. The documentation CAN be offered as a translation in other languages as well.

The documentation MUST include:

  1. Version of the extension and the document. The value MUST be a string in the format major.minor.patch as defined in Semantic Versioning 2.0.0.

  2. If the extension was updated, the document MUST include a changelog. The changelog MUST contain a summary of the changes between subsequent versions.

  3. A description of the extension, including the business case addressed by the extension and the business value gained by extending the Pathfinder Data Model. 2.1 This includes methodological alignment of the extension, especially covering the alignment with the Pathfinder Framework if applicable.

  4. A public URL to the § 4.3 Extension Schema File.

  5. A license declaration covering the documentation, the extension schema file, and their use.

  6. Electronic contact information on how to get in touch with the authors and maintainers of the extension.

5. JSON Representation of a Data Model Extension

The JSON representation of a data model extension is a JSON object.

Example representation: 
{
    "specVersion": "2.0.0",
    "dataSchema": "https://catalog.carbon-transparency.com/shipment/1.0.0/schema.json",
    "documentation": "https://catalog.carbon-transparency.com/shipment/1.0.0/documentation/",
    "data": { ... }
}

The following properties are REQUIRED:

Property specVersion

The version of the Data Model Extension specification. The value MUST be a string in the format major.minor.patch as defined in Semantic Versioning 2.0.0. This value MUST be 2.0.0 when referencing this specification.

Property dataSchema

The value MUST be the URL to the publicly accessible § 4.3 Extension Schema File encoded as a string

Property data

The value MUST be a JSON Object that conforms to the extension schema file referenced by the dataSchema property.

The following property is RECOMMENDED:

Property documentation

The value MUST be the URL to the publicly accessible § 4.4 Extension Documentation encoded as a string

The URLs for properties dataSchema and documentation MUST use the HTTPS schema.

6. Encoding and Integration of Extensions into the Pathfinder Data Model

Note: this section is work in progress

A ProductFootprint can be extended with 1 or more data model extensions. In this case, the ProductFootprint MUST include the property extensions. The value of property extensions is an array of data model extension representations (§ 5 JSON Representation of a Data Model Extension).

6.1. Example

A ProductFootprint example record with 2 imaginary extensions.

{  "data": [    {      "id": "d9be4477-e351-45b3-acd9-e1da05e6f633",      "specVersion": "1.0.0",      "version": 0,      "created": "2022-05-22T21:47:32Z",      "companyName": "My Corp",      "companyIds": [        "urn:uuid:51131FB5-42A2-4267-A402-0ECFEFAD1619",        "urn:epc:id:sgln:4063973.00000.8"      ],      "productDescription": "Cote'd Or Ethanol",      "productIds": [        "urn:gtin:4712345060507"      ],      "productCategoryCpc": "3342",      "productNameCompany": "Green Ethanol",      "comment": "",      "pcf": {        "declaredUnit": "liter",        "unitaryProductAmount": "12.0",        "pCfExcludingBiogenic": "0.0",        "pCfIncludingBiogenic": "0.0",        "fossilGhgEmissions": "0.123",        "fossilCarbonContent": "0.0",        "biogenicCarbonContent": "0.0",        "landManagementGhgEmissions": "0.001",        "otherBiogenicGhgEmissions": "0",        "characterizationFactors": "AR5",        "crossSectoralStandardsUsed": [          "GHG Protocol Product standard"        ],        "productOrSectorSpecificRules": [          {            "operator": "EPD International",            "ruleNames": [              "ABC 2021"            ]          }        ],        "boundaryProcessesDescription": "End-of-life included",        "reportingPeriodStart": "2021-01-01T00:00:00Z",        "reportingPeriodEnd": "2022-01-01T00:00:00Z",        "geographyCountry": "FR",        "secondaryEmissionFactorSources": [          {            "name": "Ecoinvent",            "version": "1.2.3"          }        ],        "dqi": {          "coveragePercent": 100.0,          "technologicalDQR": 1.13,          "temporalDQR": 2.57,          "geographicalDQR": 1.0,          "completenessDQR": 2.6,          "reliabilityDQR": 1.79        },        "assurance": {          "coverage": "product line",          "level": "reasonable",          "boundary": "Cradle-to-Gate",          "providerName": "My Auditor",          "completedAt": "2022-12-08T14:47:32Z",          "standard": "ISO ...",          "statementOrSignature": {            "type": "signature",            "value": "..."          },          "comments": "This is a comment"        },        "extensions": [          {            "specVersion": "2.0.0",            "dataSchema": "https://catalog.carbon-transparency.com/shipment/1.0.0/schema.json",            "data": {              "shipmentId": "1234567890",              "consignmentId": "abcdefghi",              "shipmentType": "PICKUP",              "weight": 10,              "transportChainElementId": "ABCDEFGHI"            }          },          {            "specVersion": "2.0.0",            "dataSchema": "https://catalog.carbon-transparency.com/primary-data-share/1.0.0/schema.json",            "data": {              "primaryDataShareScope2": 67.2,              "primaryDataShareScope3": 12.3            }          }        ],        "exemptedEmissionsPercent": "0.0",        "exemptedEmissionsDescription": "",        "packagingEmissionsIncluded": false,        "primaryDataShare": 56.12      }    }  ]}

The JSON schema file of the primary data share disclosure extension:

{
  "$id": "https://catalog.carbon-transparency.com/shipment/1.0.0/schema.json",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "PACT Primary Data Share Extension Schema",
  "description": "A Pathfinder Data Model Extension to disclose Scope 2 and Scope 3 primary data shares.",
  "required": [
    "primaryDataShareScope2",
    "primaryDataShareScope3"
  ],
  "type": "object",
  "properties": {
    "primaryDataShareScope2": {
      "type": "number",
      "minimum": 0,
      "maximum": 100
    },
    "primaryDataShareScope3": {
      "type": "number",
      "minimum": 0,
      "maximum": 180
    }
  }
}

7. Interoperability

7.1. Completeness

The representation of a data extension with respect to the data property MUST be complete.

See Criterion 6 (Completeness) of the Guidance [EXTENSIONS-GUIDANCE] for details.

7.2. Extension Data Acceptance

Host Systems MUST accept data model extensions that are conforming with this specification.

Host Systems MUST accept data model extensions that are conforming with this specification especially if they are not supported by the Host System.

Note: Host Systems are assumed to follow the "robustness principle".

Note: The specification is lacking a definition for the case that a host system does not support a specific version of an extension.

Conformance

Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.

All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

Examples in this specification are introduced with the words “for example” or are set apart from the normative text with class="example", like this:

This is an example of an informative example.

Informative notes begin with the word “Note” and are set apart from the normative text with class="note", like this:

Note, this is an informative note.

Index

Terms defined by this specification

References

Normative References

[DATA-EXCHANGE-PROTOCOL]
Pompéry, Martin; Valeri, Cecilia. Technical Specifications for PCF Data Exchange (Version 2.0.0). LS. URL: https://wbcsd.github.io/data-exchange-protocol/v2/
[EXTENSIONS-GUIDANCE]
Guidance and Criteria Catalog for Pathfinder Data Model Extensions. LS. URL: https://wbcsd.github.io/data-model-extensions/guidance/
[PATHFINDER-FRAMEWORK]
Pathfinder Framework: Guidance for the Accounting and Exchange of Product Life Cycle Emissions (Version 2.0). LS. URL: https://wbcsd.github.io/tr/2023/framework-20232601/framework.pdf
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://datatracker.ietf.org/doc/html/rfc2119
[RFC3986]
T. Berners-Lee; R. Fielding; L. Masinter. Uniform Resource Identifier (URI): Generic Syntax. January 2005. Internet Standard. URL: https://www.rfc-editor.org/rfc/rfc3986
[SEMVER]
Tom Preston-Werner. Semantic Versioning. 1 January 2013. Informational. URL: https://semver.org/spec/v2.0.0.html