Technical Specifications for PCF Data Exchange (Version 2.0.1-20231026)

1. Introduction

This document contains the necessary technical foundation for the Pathfinder Network, an open and global network for emission data exchange.

The goal of this document is to enable the interoperable exchange of Product Carbon Footprints across conforming host systems.

The methodological foundation of the specification is the Pathfinder Framework Version 2.0 ([PATHFINDER-FRAMEWORK]).

This specification document is a work in progress. It is not yet a "final" or otherwise published version. The latest published version (2.0.0) can be accessed here.

1.1. Status of This Document

Comments regarding this document are welcome. Please file issues directly on GitHub, or send them to public-dev@pathfinder.sine.dev.

This document was published by Partnership for Carbon Transparency (PACT) after an update to the Pathfinder Framework) was made.

The technical specifications within this document are the result of consent processes by PACT members and the WBCSD.

PACT recommends the wide deployment of this specification.

1.2. Scope

The scope of this document is to reach interoperability for product-level GHG emission data exchange through the definition of a data model (§ 4 Data Model) based on the Pathfinder Framework Version 2.0 and the definition of a HTTP REST API (§ 6 HTTP REST API).

1.3. Intended Audience

This technical specification is for

• software developers who want to build software for the exchange of product footprints according to the Pathfinder Framework;

• auditors and sustainability experts who want to understand the data semantics of product footprints or how they are exchanged between partners; and

• anyone that wants to understand more about the technological foundations of the Pathfinder Network.

1.4. About PACT and the Pathfinder Network

The Pathfinder Network is a concept developed by PACT and powered by the World Business Council for Sustainable Development (WBCSD). PACT is working toward the vision of an open and global network of interoperable solutions for the secure peer-to-peer exchange of accurate, primary and verified product emissions data – across all industries and value chains.

For further information, please refer to the PACT website and the Pathfinder vision paper.

1.5. Disclaimer

While PACT encourages the implementation of the technical specifications by all entities to start creating a harmonized system, neither PACT, WBCSD, nor any other individuals who contributed to the development of this document assume responsibility for any consequences or damages resulting directly or indirectly from the use of this document.

1.6. Acknowledgements

WBCSD would like to thank all PACT members, WBCSD staff, and others who shared their detailed and thoughtful input and contributed actively to the development of this document.

WBCSD would also like to express special thanks to the companies participating in the pilot for testing the interoperable exchange of GHG emissions data across different solutions, as well as to those Solution Providers who have contributed to this document.

1.7. License

The license can be found in Appendix A: License.

2. Terminology

Data Model Extension

A data model extension is a set of definitions that extends the data model of this document.

The encoding of a data model extension in the data model is specified in § 4.5 Data Type: DataModelExtension.

See [DATA-MODEL-EXTENSIONS] and [EXTENSIONS-GUIDANCE] for further details.

Data recipient

The Supply Chain Actor requesting and/or receiving PCF data from another SCA.

Data owner

The Supply Chain Actor (SCA) exchanging PCF data with another SCA.

interoperable

The quality of being able to exchange data between host systems irrespective of the vendors of the host systems, without the need for translation or transformation of the data.

Greenhouse Gas (emissions) (GHG)

Gaseous constituents of the atmosphere, both natural and anthropogenic, that absorb and emit radiation at specific wavelengths within the spectrum of infrared radiation emitted by the Earth’s surface, its atmosphere and clouds. GHGs include CDCO₂, Methane (CH4), Nitrous Oxide(N₂O), Hydrofluoro-Carbons (HFCs), Perfluorocarbons (PFCs) and Sulfur Hexafluoride (SF6).

Partnership for Carbon Transparency (PACT)

A WBCSD-led group of companies and organizations working together to develop a global and open network for the secure peer-to-peer exchange of accurate, primary and verified product emissions data. See www.carbon-transparency.com for more information.

Pathfinder Framework Version 2.0 (Pathfinder Framework)

Guidance for the Accounting and Exchange of Product Life Cycle Emissions, building on existing standards and protocols, such as the GHG Protocol Product standard. See [PATHFINDER-FRAMEWORK] for further details.

Pathfinder Network

An information network of and for supply chain actors to securely exchange environmental data with each other, with an initial focus on PCF data.

Product Carbon Footprint (PCF)

The carbon (equivalent) emissions relating to a product. Products can be any kind of item exchanged between entities, including metric or volumetric quantities of a product. The ProductFootprint data model is a digital representation of a PCF in accordance with the Pathfinder Framework.

Supply Chain Actor (SCA)

An entity intending on exchanging PCF data with another entity using the technical means specified in this document.

Solution Provider

An entity providing technical solutions to SCAs by implementing and offering host systems.

UN geographic region, UN geographic subregion

See https://unstats.un.org/unsd/methodology/m49/ for details.

3. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words MAY, MUST, MUST NOT, OPTIONAL, RECOMMENDED, REQUIRED, SHOULD, and SHOULD NOT in this document are to be interpreted as described in [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

A conforming host system is any algorithm realized as software and/or hardware that complies with the relevant normative statements in § 6 HTTP REST API.

A conforming requesting data recipient is any algorithm realized as software and/or hardware that complies with the relevant normative statements in § 6 HTTP REST API.

4. Data Model

This section specifies a data model for product footprints conforming with the Pathfinder Framework Version 2.

The data model consists of the following major data types:

1. ProductFootprint: contains information to identify a product, plus further information such as the CarbonFootprint (see § 4.1 Data Type: ProductFootprint)

2. CarbonFootprint: contains information related to the carbon footprint of a product (see § 4.2 Data Type: CarbonFootprint)

3. DataModelExtension: contains additional information beyond the data model specified in this document.

The overall data model is designed for interactions between data owners and data recipients, to enable (i) interoperability, (ii) comparability of and transparency over product footprints, or (iii) the calculation of derived CarbonFootprints from other CarbonFootprints.

Additional uses of the data model are supported through the concept of Data Model Extensions. These allow data owners to add further information to a ProductFootprint.

4.1. Data Type: ProductFootprint

ProductFootprint is a data type which represents the carbon footprint of a product under a specific scope (§ 4.2.1 Scope of a CarbonFootprint) and with values calculated in accordance with the Pathfinder Framework.

The objective of a ProductFootprint is to provide interoperability between the creator (the data owner) and the consumer (the data recipient) of ProductFootprints. The details on the exchange of ProductFootprints are specified in § 6 HTTP REST API.

Conceptually, the data type ProductFootprint is modeled as a multi-purpose container for product-specific emissions factors which is supported by extensibility through Data Model Extensions.

Data Model Extensions enable data owners to exchange additional information related to a product with data recipients. The details are specified in § 4.5 Data Type: DataModelExtension as well as [EXTENSIONS-GUIDANCE], and [DATA-MODEL-EXTENSIONS].

Each ProductFootprint can and should be updated over time, for instance to incorporate new or refined data from data owners (see § 5 Product Footprint Lifecycle).

4.1.1. Properties

A ProductFootprint has the following properties:

4.2. Data Type: CarbonFootprint

A CarbonFootprint represents the carbon footprint of a product and related data in accordance with the Pathfinder Framework.

4.2.1. Scope of a CarbonFootprint

Each CarbonFootprint is scoped by

1. Time Period: the time period is defined by the properties referencePeriodStart and referencePeriodEnd (see Pathfinder Framework section 6.1.2.1)

2. Geography: further set by the properties geographyRegionOrSubregion, geographyCountry, and geographyCountrySubdivision (see Pathfinder Framework section 6.1.2.2)

If a CarbonFootprint

1. Has geographical granularity Global, then the properties geographyCountry and geographyRegionOrSubregion and geographyCountrySubdivision MUST be undefined;

2. Has a regional or sub-regional geographical granularity, then the property geographyRegionOrSubregion MUST be defined and the properties geographyCountry and geographyCountrySubdivision MUST be undefined;

3. Has a country-specific geographical granularity, then property geographyCountry MUST be defined AND the properties geographyRegionOrSubregion and geographyCountrySubdivision MUST be undefined;

4. Has a country subdivision-specific geographical granularity, then property geographyCountrySubdivision MUST be defined AND the properties geographyRegionOrSubregion and geographyCountry MUST be undefined.

An overview of the relationship between the geographic scope and the definedness or undefinedness of properties is given in the following table:

4.2.2. Properties

The properties of a CarbonFootprint are listed in the table below.

The properties marked with O* are OPTIONAL only for reporting periods before 2025, and for reporting periods including the beginning of calendar year 2025 or later, the properties marked with O* MUST be defined.

4.3. Data Type: DataQualityIndicators

Data type DataQualityIndicators contains the quantitative data quality indicators in conformance with Pathfinder Framework Section 4.2.3 and Appendix B.

Each property is optional until the reporting period includes the beginning of calendar year 2025, or later, when all properties MUST be defined.

The following properties are defined for data type DataQualityIndicators:

{
  "assurance": true,
  "coveragePercent": 42.0,
}

{
  "technologicalDQR": 2.0,
  "temporalDQR": 2.0,
  "geographicalDQR": 2.0,
  "completenessDQR": 2.0,
  "reliabilityDQR": 2.0
}

4.4. Data Type: Assurance

Data type Assurance contains the assurance in conformance with Pathfinder Framework chapter 5 and appendix B.

The following properties are defined for data type Assurance:

4.5. Data Type: DataModelExtension

Each data model extension MUST be a valid JSON object conforming with the JSON Representation of Data Model Extensions (§ 5. JSON Representation of a Data Model Extension).

See [DATA-MODEL-EXTENSIONS] for technical details and [EXTENSIONS-GUIDANCE] for data model extension guidance.

{
  "specVersion": "2.0.1",
  "dataSchema": "https://catalog.carbon-transparency.com/shipment/1.0.0/data-model.json",
  "data": {
    "shipmentId": "S1234567890",
    "consignmentId": "Cabc.def-ghi",
    "shipmentType": "PICKUP",
    "weight": 10,
    "transportChainElementId": "ABCDEFGHI"
  }
}

4.6. Data Type: RegionOrSubregion

The data type RegionOrSubregion MUST be encoded as a String with value equal to one of the following values:

Africa

for the UN geographic region Africa

Americas

for the UN geographic region Americas

Asia

for the UN geographic region Asia

Europe

for the UN geographic region Europe

Oceania

for the UN geographic region Oceania

Australia and New Zealand

for the UN geographic subregion Australia and New Zealand

Central Asia

for the UN geographic subregion Central Asia

Eastern Asia

for the UN geographic subregion Eastern Asia

Eastern Europe

for the UN geographic subregion Eastern Europe

Latin America and the Caribbean

for the UN geographic subregion Latin America and the Caribbean

Melanesia

for the UN geographic subregion Melanesia

Micronesia

for the UN geographic subregion Micronesia

Northern Africa

for the UN geographic subregion Northern Africa

Northern America

for the UN geographic subregion Northern America

Northern Europe

for the UN geographic subregion Northern Europe

Polynesia

for the UN geographic subregion Polynesia

South-eastern Asia

for the UN geographic subregion South-eastern Asia

Southern Asia

for the UN geographic subregion Southern Asia

Southern Europe

for the UN geographic subregion Southern Europe

Sub-Saharan Africa

for the UN geographic subregion Sub-Saharan Africa

Western Asia

for the UN geographic subregion Western Asia

Western Europe

for the UN geographic subregion Western Europe

4.7. Data Type: EmissionFactorDSSet

A set of Emission Factor Data Sources of size 1 or larger.

4.7.1. JSON Data Representation

As an array of objects, with each object conforming to the JSON representation of EmissionFactorDS.

4.8. Data Type: EmissionFactorDS

An EmissionFactorDS references emission factor databases (see Pathfinder Framework Section 4.1.3.2).

4.8.1. Properties

name (mandatory, data type: NonEmptyString)

The non-empty name of the emission factor database.

version (mandatory, data type: NonEmptyString)

The non-empty version of the emission factor database.

{
  "name": "ecoinvent",
  "version": "3.9.1"
}

4.8.2. JSON Representation

Each EmissionFactorDS MUST be encoded as a JSON object.

4.9. Data Type: CrossSectoralStandard

CrossSectoralStandard is the enumeration of accounting standards used for product carbon footprint calculation. Valid values are

GHG Protocol Product standard

for the GHG Protocol Product standard

ISO Standard 14067

for ISO Standard 14067

ISO Standard 14044

for ISO Standard 14044

4.9.1. JSON Representation

Each CrossSectoralStandard MUST be encoded as a JSON string.

4.10. Data Type: CrossSectoralStandardSet

A set of CrossSectoralStandard values.

4.10.1. JSON Representation

As an array of strings, with each string conforming to the JSON representation of CrossSectoralStandard.

4.11. Data Type: ProductOrSectorSpecificRule

A ProductOrSectorSpecificRule refers to a set of product or sector specific rules published by a specific operator and applied during product carbon footprint calculation.

4.11.1. Properties

operator (mandatory, data type: ProductOrSectorSpecificRuleOperator)

A ProductOrSectorSpecificRule MUST include the property operator with the value conforming to data type ProductOrSectorSpecificRuleOperator.

ruleNames (mandatory, data type: NonEmptyStringVector)

A ProductOrSectorSpecificRule MUST include the property ruleNames with value the non-empty set of rules applied from the specified operator.

otherOperatorName (optional, data type: NonEmptyString)

If the value of property operator is Other, a ProductOrSectorSpecificRule MUST include the property otherOperatorName with value the name of the operator. In this case, the operator declared MUST NOT be included in the definition of ProductOrSectorSpecificRuleOperator. If the value of property operator is NOT Other, the property otherOperatorName of a ProductOrSectorSpecificRule MUST be undefined.

4.11.2. JSON Representation

Each ProductOrSectorSpecificRule MUST be encoded as a JSON object.

4.12. Data Type: ProductOrSectorSpecificRuleSet

A set of ProductOrSectorSpecificRule of size 1 or larger.

4.12.1. JSON Representation

Each ProductOrSectorSpecificRuleSet MUST be encoded as an array of JSON objects, with each object conforming to § 4.11.2 JSON Representation.

4.13. Data Type: ProductOrSectorSpecificRuleOperator

A ProductOrSectorSpecificRuleOperator is the enumeration of Product Category Rule (PCR) operators. Valid values are:

PEF

for EU / PEF Methodology PCRs

EPD International

for PCRs authored or published by EPD International

Other

for a PCR not published by the operators mentioned above

4.13.1. JSON Representation

Each value is encoded as a JSON String.

4.14. Data Type: NonEmptyStringVector

A list of NonEmptyString of length 1 or greater.

4.14.1. JSON Representation

Each NonEmptyStringVector MUST be encoded as an array of NonEmptyStrings.

4.15. Data Type: CpcCode

A CpCode represents a UN CPC Code version 2.1 value.

Example value of the CPC code for "wood in chips or particles":

4.15.1. JSON Representation

Each CpcCode MUST be encoded as a JSON String.

4.16. Data Type: DeclaredUnit

DeclaredUnit is the enumeration of accepted declared units with values

liter

for special SI Unit litre (see [SI-Unit] Table 8)

kilogram

for SI Base Unit kilogram (see [SI-Unit])

cubic meter

for cubic meter, the Derived Unit from SI Base Unit metre

kilowatt hour

for kilowatt hour, the Derived Unit from special SI Unit watt

megajoule

for megajoule, the Derived Unit from special SI Unit joule

ton kilometer

for ton kilometer, the Derived Unit from SI Base Units kilogram and metre

square meter

for square meter, the Derived Unit from SI Base Unit metre

4.16.1. JSON Representation

The value of each DeclaredUnit MUST be encoded as a JSON String.

4.17. Data Type: NonEmptyString

A String with 1 or more characters.

4.17.1. JSON Representation

Each NonEmptyString MUST be encoded as a JSON String.

4.18. Data Type: CompanyIdSet

A set of CompanyIds of length 1 or greater.

4.19. Data Type: CompanyId

Each CompanyId MUST be a URN.

4.19.1. Custom Company Ids (Company Codes)

If the data owner (SCA) wishes to use a custom company code assigned to it by a data recipient as a CompanyId value, the data owner SHOULD use the following format:

urn:pathfinder:company:customcode:buyer-assigned:$custom-company-code$

where $custom-company-code$ stands for the custom company code assigned by the data recipient.

If the data owner (SCA) wishes to use its own custom company code known by a data recipient as a CompanyId value, the data owner SHOULD use the following format:

urn:pathfinder:company:customcode:vendor-assigned:$custom-company-code$

where $custom-company-code$ stands for the custom company code set by the data recipient.

4.20. Data Type: ProductIdSet

A set of ProductIds of size 1 or larger.

4.20.1. JSON Representation

Each ProductIdSet MUST be encoded as an array of strings.

4.21. Data Type: ProductId

Each ProductId MUST be a URN.

4.21.1. Custom Product Ids (Product Codes)

If the data owner (SCA) wishes to use a custom product code assigned to it by a data recipient as a ProductId value, the data owner SHOULD use the following format:

urn:pathfinder:product:customcode:buyer-assigned:$CUSTOM-PRODUCT-CODE$

where $CUSTOM-PRODUCT-CODE$ stands for the custom product code assigned by the data recipient.

If the data owner (SCA) wishes to use its own custom product code known by a data recipient as a ProductId value, the data owner SHOULD use the following format:

urn:pathfinder:product:customcode:vendor-assigned:$CUSTOM-PRODUCT-CODE$

where $CUSTOM-PRODUCT-CODE$ stands for the custom product code set by the data recipient.

4.21.2. ProductId based on CAS Registry Numbers

If the data owner (SCA) wishes to use a CAS Registry Number as a ProductId value, the data owner SHOULD use the following format:

urn:pathfinder:product:id:cas:$CAS-REGISTRY-NUMBER$

where $CAS-REGISTRY-NUMBER$ stands for a CAS Registry Number.

4.21.3. ProductId based on IUPAC InChi Code

If the data owner (SCA) wishes to use a IUPAC InChi Code as a ProductId value, the data owner SHOULD use the following format:

urn:pathfinder:product:id:iupac-inchi:$INCHI-CODE$

where $INCHI-CODE$ stands for a IUPAC InChi Code.

urn:pathfinder:product:id:iupac-inchi:1S%2FC9H8O4%2Fc1-6%2810%2913-8-5-3-2-4-7%288%299%2811%2912%2Fh2-5H%2C1H3%2C%28H%2C11%2C12%29

4.22. Data Type: URN

A String conforming to the URN syntax.

4.22.1. JSON Representation

Each URN MUST be encoded as a JSON String.

4.23. Data Type: String

A regular UTF-8 String.

4.23.1. JSON Data Representation

Each String MUST be encoded as a JSON String.

4.24. Data Type: Percent

A Decimal number in the range of and including 0 and 100.

Example values:

4.24.1. JSON Representation

Each Percent MUST be encoded in IEEE-754 double-precision floating-point format as a JSON number.

4.25. Data Type: StrictlyPositiveDecimal

A positive, non-zero Decimal.

Example values:

4.25.1. JSON Representation

See [§ 4.28.1 JSON Representation].

4.26. Data Type: DateTime

Each DateTime MUST be a date and time string conforming to ISO 8601. The timezone MUST be UTC.

Example value for beginning of March, the year 2020, UTC:

4.26.1. JSON Representation

Each DateTime MUST be encoded as a JSON String.

4.27. Data Type: ISO3166CC

An ISO 3166-2 alpha-2 country code.

Example value for tue alpha-2 country code of the United States:

4.27.1. JSON Representation

Each ISO3166CC MUST be encoded as a JSON String.

4.28. Data Type: Decimal

A dotted-decimal number.

Example values:

4.28.1. JSON Representation

Each Decimal MUST be encoded as a JSON String.

4.29. Data Type: PfId

A PfId MUST be a UUID v4 as specified in [RFC4122].

4.29.1. JSON Representation

Each PfId MUST be encoded as a JSON String.

Example JSON string value:

"f4b1225a-bd44-4c8e-861d-079e4e1dfd69"

5. Product Footprint Lifecycle

5.1. Introduction

The contents of a Product Footprints can change over time. For instance when a data owner publishes an updated Product Footprint ("upstream Product Footprints") which goes into the calculation of another Product Footprint ("downstream Product Footprint").

Even without upstream changes, a downstream Product Footprint can undergo changes in its own right, for instance when calculation errors are discovered and fixed, or when secondary emission databases are updated.

This section defines how changes to Product Footprints shall be handled by data owners and communicated to data recipients through the ProductFootprint data model.

For this, changes to ProductFootprint properties are defined and classified into minor change and major change (§ 5.2 Change Definition and Classification). Depending on the change classification,

1. major changes must result in a new ProductFootprint (§ 5.4 New ProductFootprint creation from major changes) made available to its data recipients,

2. minor changes result in either version updates (§ 5.3 ProductFootprint version creation from minor changes) or new ProductFootprint creation (§ 5.4 New ProductFootprint creation from major changes)

In addition, if a Product Footprint is no longer valid, data owners can communicate this by applying a minor change through setting the status to Deprecated

5.2. Change Definition and Classification

A change to a ProductFootprint is defined as a change to one or more properties of a ProductFootprint, including a change of 1 or more properties from being undefined or to no longer being defined.

A ProductFootprint with status Deprecated MUST NOT be changed.

There are 2 classes of changes to a ProductFootprint:

minor change

A minor change refers to a set of 1 or more changes to attributes to a ProductFootprint, including embedded data such as CarbonFootprint, etc.

minor changes to a ProductFootprint SHOULD BE limited to correct errors, to incorporate changes in upstream data sources, or to incorporate changes in secondary data sources.

A minor change is limited to the following CarbonFootprint properties:

1. pCfExcludingBiogenic, pCfIncludingBiogenic, fossilCarbonContent, biogenicCarbonContent, dLucGhgEmissions, landManagementGhgEmissions, otherBiogenicGhgEmissions, iLucGhgEmissions, biogenicCarbonWithdrawal, aircraftGhgEmissions, packagingEmissionsIncluded, packagingGhgEmissions, fossilGhgEmissions, biogenicCarbonContent, primaryDataShare, secondaryEmissionFactorSources, dqi, primaryDataShare as a result of a change resulting from upstream ProductFootprints or an update to secondary data sources

2. as a result of changes to the description properties boundaryProcessesDescription, allocationRulesDescription, uncertaintyAssessmentDescription

3. After a change to the assurance statement assurance from being undefined to being defined

A minor change MUST NOT change the id or the scope (§ 4.2.1 Scope of a CarbonFootprint) of the ProductFootprint.

major change

A major change refers to a set of 1 or more changes with 1 or more changes NOT conforming to the minor change definition.

Additionally, a data owner CAN decide to handle a minor change as a major change (see § 5.4 New ProductFootprint creation from major changes for further details).

5.3. ProductFootprint version creation from minor changes

A minor change to a ProductFootprint MAY result in a new version of a ProductFootprint.

The data owner CAN represent a minor change to a ProductFootprint by creating 1 or more new ProductFootprints by following the specification from § 5.4 New ProductFootprint creation from major changes.

A version update to a ProductFootprint MUST be represented in the ProductFootprint by

1. incorporating the changes

2. incrementing version by 1 (or more)

3. setting updated to the time and date of the minor change. If defined, updated MUST be strictly greater than the previous value of updated. Additionally, the value of updated MUST be strictly greater than the value of created.

5.4. New ProductFootprint creation from major changes

A Major change to 1 or more preceding ProductFootprints MUST result in

1. at least 1 new ProductFootprint being available to respective data recipients

2. for each of the preceding ProductFootprints, a new version being available to respective data recipients by

3. following § 5.3 ProductFootprint version creation from minor changes

4. setting status to Deprecated

For each new ProductFootprint, the data owner MUST

1. make the necessary calculations for the new ProductFootprint

2. assign the new ProductFootprint a unique id

3. set updated to undefined

4. set precedingPfIds to the set of id of the 1 or more preceding ProductFootprints

6. HTTP REST API

6.1. Introduction

This section defines an HTTP-based API for the interoperable exchange of Product Footprint data between host systems.

The scope of the HTTP API is minimal by design. Additional features will be added in future versions of this specification.

6.2. Host System

A host system serves the needs of a single or multiple data owners. Additionally, a host system can also serve the needs of data recipients if it retrieves data from host systems by calling the HTTP REST API (§ 6 HTTP REST API).

Interoperable data exchange between a data owner and a data recipient can be achieved by

1. the data owner offering ProductFootprint data through a host system that implements the HTTP REST API, and

2. the data recipient making authenticated calls to retrieve ProductFootprint data; e.g. by calling the Action ListFootprints.

6.2.1. Out of scope

This standard focuses on the necessary definitions to enable interoperable data exchange between data owners and data recipients. This is mediated through a host system which implements the HTTP REST API defined in this document.

Within the PACT Project, conforming host systems are called solutions.

Solutions add further functionality on top of this standard in order to enable meaningful and interoperable data exchanges.

The following section briefly describes some of the additional functionality which is beyond the scope of this document:

1. Footprint calculation according to the Pathfinder Framework
2. Authentication and access management: the act of deciding and setting which product footprint may be accessed by each data recipient
3. Credentials management: the overall functionality to generate access credentials for data recipients, to exchange these credentials with data recipients, to rotate or revoke such credentials, etc.
4. Logging: creation and storage of access logs and audit trails related to data exchange, authentication processes, etc.

6.3. Authentication and Request Flows

Data recipients MUST first retrieve an access token through Action Authenticate. This is implemented by

1. the data recipient calling Action Authenticate of a host system

2. the host system issuing an access token as specified in [rfc6749] Section 4.4.3 and Section 5.1

3. the data recipient calling one or more Actions of the host system

   • using the value of access_token of the response of the Action Authenticate call as the value for a [rfc6750] Bearer token

   • presenting the Bearer token for subsequent call(s) to the host system in accordance with [rfc6750] Section 2.1

Access tokens SHOULD expire. In this case, data recipients MUST retrieve a new access token as described in this section.

6.4. Host system minimum requirements

A host system MUST implement the following actions:

1. Action Authenticate

2. Action ListFootprints

3. Action GetFootprint

A host system SHOULD implement the following actions:

1. Action Events

A host system MUST offer its actions under https method only.

A host system MUST offer all actions under the same Hostname and Subpath except for Action Authenticate.

A host system MAY offer the Action Authenticate under a dedicated AuthHostname and AuthSubpath.

6.5. Action Authenticate

Request an access token using client credentials.

Host systems MUST implement this action in conformance with [rfc6749] Section 4.4 (OAuth2 Client Credentials).

Host systems MAY offer this action under a dedicated AuthHostname and AuthSubpath.

An access token is the value of access_token from a 200 (OK) entity-body derived from a successful call to this action. See [rfc6749] Section 4.4.3 and Section 5.1 for further details.

6.5.1. Request Syntax (HTTP/1.1)

POST AuthSubpath/auth/token HTTP/1.1
host: AuthHostname
accept: application/json
content-type: application/x-www-form-urlencoded
authorization: Basic BasicAuth
content-length: ContentLength

AuthBody

With Request parameters:

AuthSubpath:

If a host system uses a relative subpath dedicated to the purpose of creating an access token, then the requesting data recipient MUST prepend this subpath.

AuthHostname

The requesting data recipient MUST use the domain name of the host system dedicated for the purpose of creating an authentication token.

BasicAuth

See [rfc6749] Section 4.4.2

AuthBody

See [rfc6749] Section 4.4

ContentLength

The length of the Body. See [rfc9112].

6.5.2. Response Syntax

HTTP/1.1 AuthStatusCode OK
content-type: application/json
content-length: ContentLength

AuthResponseBody

With action-specific response parameters

AuthStatusCode

A HTTP response code conforming to [rfc6749] Section 4.4 and Section 5.

AuthResponseBody

A JSON Object conforming to either RFC 6749 Section 4.4 in case of successful authentication, or RFC 6749 Section 5.2 otherwise. See § 6.3 Authentication and Request Flows for further details

6.5.2.1. Example Successful Response

Example AuthResponseBody for a successful authenticate call:

{
  "access_token": "...",
  "token_type": "bearer"
}

6.5.2.2. Example Error Response

Example HTTP call, for instance generated because username or password did not match:

HTTP/1.1 401 Unauthorized
date: Mon, 23 Oct 2023 19:33:16 GMT
content-type: application/json

{
  "error": "invalid_client",
  "error_description": "Authentication failed"
}

For further details, for instance on the list of specified values of property error, consult [rfc6749] Section 5.2.

6.6. Action ListFootprints

Lists product footprints with pagination and optional filtering.

Host systems SHOULD implement an access management system and only return the product footprints for which the data owner granted access to the requesting data recipient.

6.6.1. Filtering

Filtering CAN be requested by a data recipient by setting a conforming Filter request parameter.

Note: The filter statement syntax is described at the Filter request parameter.

Support for filtering by a host system is OPTIONAL such that

1. if a host system does not implement Filtering, it MUST process the request as if no Filter was provided

2. If a host system implements Filtering, it CAN process the filter statement on a best-effort basis:

   1. it CAN ignore the filter statement or parts of the filter statement, or

   2. it CAN refuse to process the specific filter statement if it does not support the filter statement or parts of it. In this case, it MUST return an error response with code NotImplemented.

6.6.2. Pagination

Host systems MUST implement pagination server-side such that

1. The host system MAY return less ProductFootprints than requested through the Limit request parameter

2. The host system MUST return a Link header if there are additional ProductFootprints ready to be retrieved, such that

3. The Link header conforms to [RFC8288]

4. The value of the rel parameter is equal to next

5. the target IRI (RFC8288, section 3.1) of the Link header is absolute

6. The value of host of the target IRI is equal to the value of the host request header from the original ListFootprints HTTP request

The target IRI from a pagination link header is called a pagination link.

Upon a host system returning a pagination link

1. a data recipient CAN call the pagination link more than once

2. upon each call, the host system

   1. MUST return the same set of Product Footprints upon successful authentication (i.e. a Bearer token authentication as defined in § 6.3 Authentication and Request Flows)

   2. MUST NOT return more product footprints than requested in case Limit was defined by a data recipient

   3. MUST return a Link header conforming with the previous description in case there are additional ProductFootprints available

3. If a response contains a second pagination link and the data recipient upon calling the second pagination link, the previous pagination link MAY no longer work

   • i.e. data recipients MUST NOT assume that previous pagination links continue to return results after advancing in the pagination process

4. a pagination link MUST be valid for at least 180 seconds after creation

5. a data recipient SHOULD retry calling the pagination link after the server returned an error

6. and SHOULD use a randomized exponential back-off strategy when retrying

6.6.3. Request Syntax (HTTP/1.1)

GET Subpath/2/footprints?Filter&Limit HTTP/1.1
host: Hostname
authorization: Bearer BearerToken

with request parameters:

Subpath

If a host system uses a relative subpath, then the requesting data recipient MUST prepend this subpath.

Hostname

The requesting data recipient MUST use the domain name of the host system.

BearerToken

see Bearer Token of section § 6.3 Authentication and Request Flows

Filter

Filter is an OPTIONAL request parameter. If defined,

1. the name of the HTTP request parameter MUST be $filter

2. the value of the HTTP request parameter MUST conform to the $filter syntax as defined by the ODatav4 specification.

Additionally, the $filter statement MUST only include the following operators and properties:

• Logical operators eq, lt, le, gt, ge on properties created, updated, productCategoryCpc, geographyCountry, referencePeriodStart, referencePeriodEnd.

• Logical operator and.

• Lambda operator any on collection-valued properties companyIds, productIds. The expression argument of the operator MUST only include the eq operator.

Get footprints with CPC code "3342":

$filter=productCategoryCpc eq '3342'

Get footprints scoped for country:

$filter=pcf/geographyCountry eq 'DE'

Get footprints for 2023 reporting period:

$filter=(pcf/referencePeriodStart ge '2023-01-01T00:00:00.000Z') and (pcf/referencePeriodEnd lt '2024-01-01T00:00:00.000Z')

Get footprints for a specific product:

$filter=productIds/any(productId:(productId eq 'urn:...'))

Limit

Limit is an OPTIONAL request parameter. If defined,

1. the name of the HTTP request parameter MUST be limit

2. and the value MUST be a positive integer.

6.6.4. Response Syntax

HTTP/1.1 ListStatusCode ListStatusText
content-type: application/json
content-length: ContentLength

ListResponseBody

With response parameters

ListStatusCode

If the host system returns a list of product footprints, the HttpStatusCode MUST be either 200 or 202:

• HttpStatusCode 200 indicates the returned list is the complete result of the given query.

• HttpStatusCode 202 indicates the returned list is an incomplete result of the given query. The host system MAY return this HttpStatusCode if it principally decides that it’s able to obtain the remaining data in the future. This HttpStatusCode MUST NOT be returned if the request parameter Filter is not defined. The data recipient MAY continue to send the same request with exponential-backoff until it receives the complete result, indicated by HttpStatusCode 200.

If the host system responds with an error response, the HttpStatusCode MUST match the HTTP Status Code of the respective error response code.

If the host system does not return the list of ProductFootprints, it MUST return an error HTTP Status Code (4xx, 5xx).

ListStatusText

The HTTP Status text conforming to the HTTP status code ListStatusCode.

ListResponseBody

If the host system accepts the access token, the body MUST be a JSON object with property data with value the list of ProductFootprints. The list MUST be encoded as a JSON array. If the list is empty, the host system MUST return an empty JSON array.

The host system MUST return the latest version of each footprint and MAY return previous versions. Among the footprints with identical id values, the one with the maximum version value is called the latest version and the rest are called the previous versions.

If the request parameter Filter is defined, the specified expression SHOULD be evaluated for each ProductFootprint in the collection as described in OData v4 specification, and only ProductFootprints where the expression evaluates to true SHOULD be included in the response. ProductFootprints for which the expression evaluates to false or which are not made available for the data recipient SHOULD be omitted from the list returned in the response.

If the host system does not accept the access token, the body MUST be an error response with code AccessDenied.

If the host system does not accept the access token because it expired, the body SHOULD be an error response with code TokenExpired.

In all other cases, for instance in case of a malformed value of the header authorization, the body SHOULD be an error response with code BadRequest.

6.7. Action GetFootprint

Retrieves product footprints.

Host systems SHOULD implement an access management system and only return the product footprints for which the data owner granted access to the requesting data recipient.

6.7.1. Request Syntax

GET Subpath/2/footprints/GetPfId HTTP/1.1
Host: Hostname
authorization: Bearer BearerToken

with request-specific parameters:

GetPfId

The value of property id of a product footprint a data recipient intends to retrieve.

6.7.2. Response Syntax

HTTP/1.1 GetStatusCode GetStatusText
content-type: application/json
content-length: ContentLength

GetResponseBody

With response parameters:

GetStatusCode

The HTTP Status Code of the response.

If the host system accepts the access token, the HTTP Status Code MUST be 200.
If the host system responds with an error response, the HTTP status code MUST match the HTTP Status Code of the respective error response code.
If the host system does NOT return a product footprint, the host system MUST return an error HTTP Status Code (4xx, 5xx).

GetStatusText

The HTTP Status text conforming to the HTTP status code GetStatusCode.

GetResponseBody

If the host system accepts the access token and allows the requesting data recipient to access the requested product footprint, the body MUST be a JSON object with property data. The value of property data MUST be the product footprint with footprint identifier GetPfId.

If there were changes to the requested product footprint with identifier GetPfId, the host system SHOULD return the latest product footprint identified with identifier GetPfId and the maximum value of property version.

Note: If a host system implements the life cycle rules, then the “latest” version of the requested product footprint is the one with the maximum value of version with id equal to GetPfId.

If the host system does not accept the access token, GetResponseBody MUST be an error response with code AccessDenied.

If the host system does not accept the access token because it expired, GetResponseBody SHOULD be an error response with code TokenExpired.

The host system MAY return an error response with code NoSuchFootprint.

In all other cases, for instance in case of a malformed value of the header authorization, GetResponseBody SHOULD be an error response with code BadRequest.

6.8. Action Events

The Action Events enables the exchange of event data between data owners and data recipients.

The Action Events endpoint is specified for the following use cases:

1. enabling a data owner to notify a data recipient on updates to 1 or more Product Footprints (see § 6.8.3 Notification of data recipients on Product Footprint updates)

2. enabling a data recipient to request product footprints from a data owner by sending an event to the data owner’s Action Events endpoint (see § 6.8.4 Asynchronous request and retrieval of Product Footprints).

A host system SHOULD only accept events after authentication (see § 6.3 Authentication and Request Flows).

The Action Events endpoint accepts CloudEvent events (see [CE]) encoded in "Structured Content Mode" (see [CE-Structured-Content-Mode].

Support for Action Events is OPTIONAL.

If a host system does NOT implement the Action Events endpoint,

1. it SHOULD respond with a conforming error response and HTTP error response code.

2. it SHOULD respond to authenticated Action Events calls with an error response with code NotImplemented.

3. it MUST respond with an error HTTP Status Code (4xx, 5xx).

6.8.1. Request Syntax

The general request syntax is:

POST Subpath/2/events HTTP/1.1
host: Hostname
authorization: Bearer BearerToken
content-type: application/cloudevents+json; charset=UTF-8

EventBody

With request parameters:

EventBody

The EventBody MUST be

1. a CloudEvents event (see [CE])

2. encoded as a JSON object as defined in [CE-JSON]

3. using "Structured Content Mode" (see [CE-Structured-Content-Mode]).

Further details on the EventBody syntax and semantics are given in § 6.8.3 Notification of data recipients on Product Footprint updates and § 6.8.4 Asynchronous request and retrieval of Product Footprints.

6.8.2. Response Syntax

The host system upon accepting the event MUST respond with HTTP Status Code 200 and an empty body:

HTTP/1.1 200 OK
content-length: 0

The host system upon not accepting the event SHOULD respond with an error response (see § 6.9 Error responses).

6.8.3. Notification of data recipients on Product Footprint updates

A data owner CAN notify a data recipient about changes to 1 or more product footprints by sending a PF Update Event to the data recipient’s Action Events endpoint.

A data recipient upon receiving such an PF Update Event CAN retrieve the product footprints through the Action GetFootprint.

Accordingly, the data owner of the host system sending the event MUST make the referenced Product Footprints available to the data recipient notified through the PF Update Event.

The PF Update Event is defined as a JSON-encoded CloudEvent event with the following syntax:

{
  "type": "org.wbcsd.pathfinder.ProductFootprint.Published.v1",
  "specversion": "1.0",
  "id": "EventId",
  "source": "//EventHostname/EventSubpath",
  "time": "2022-05-31T17:31:00Z",
  "data": {
    "pfIds": PfIds
  }
}

with

EventId

A unique identifier for the event set by the host system sending the event. The EventId MUST be a string (see [CE-JSON]).

PfIds

A list of product footprint that have been updated. The PfIds MUST be the non-empty list of id values of the updated Product Footprints, encoded as a JSON array.

EventHostname

The Hostname of the host system sending the event.

EventSubpath

The handler of the host system sending the event.

6.8.4. Asynchronous request and retrieval of Product Footprints

A data recipient CAN request a data owner to send a product footprint by sending a PF Request Event to the data owner’s Action Events endpoint.

A data owner upon receiving a PF Request Event can then decide how to process the request

1. by sending a PF Response Event to the data recipient’s Action Events endpoint

2. by sending a PF Response Error Event to the data recipient’s Action Events endpoint to notify the data recipient that the request cannot be processed, or

3. by not sending any event to the data recipient’s Action Events endpoint.

If a data owner accepted a PF Request Event, the host system MUST send the response back to the host system referenced in source of the PF Request Event.

The host system of the data owner MUST validate the value of source before sending the response.

If the host system of the original requestor (the data recipient) is not available or does not accept the response with a HTTP success code (2xx), the data owner’s host system SHOULD retry sending the response event using exponential backoff.

A host system SHOULD NOT retry sending a response event for more than 3 days.

6.8.4.1. PF Request Event syntax

The PF Request Event is defined as a CloudEvent event sent from a data recipient to a data owner. The event contains a Product Footprint fragment to describe to the data owner the requested product footprints.

The PF Request Event is defined as a JSON-encoded CloudEvent event with the following syntax:

{
  "type": "org.wbcsd.pathfinder.ProductFootprintRequest.Created.v1",
  "specversion": "1.0",
  "id": "EventId",
  "source": "//EventHostname/EventSubpath",
  "time": "2022-05-31T17:31:00Z",
  "data": {
    "pf": ProductFootprintFragment,
    "comment": PFRequestComment
  }
}

with

ProductFootprintFragment

A JSON object which references a subset of ProductFootprint properties, including nested properties.

PFRequestComment

The OPTIONAL comment by the data recipient to the data owner about the request. If defined, the PFRequestComment MUST be encoded as a JSON string.

The property data.comment of a PF Request Event is OPTIONAL.

6.8.4.2. PF Response Event syntax

The PF Response Event is defined as a CloudEvent event sent from a data owner to a data recipient after having received a PF Request Event from a data recipient and upon successfully fulfilling the request.

The PF Response Event is defined as a JSON-encoded CloudEvent event with the following syntax:

{
  "type": "org.wbcsd.pathfinder.ProductFootprintRequest.Fulfilled.v1",
  "specversion": "1.0",
  "id": "EventId",
  "source": "//EventHostname/EventSubpath",
  "data": {
    "requestEventId": "ReqEventId",
    "pfs": Pfs
  }
}

with

ReqEventId

The EventId of the PF Request Event that the PF Response Event is responding to. The ReqEventId MUST be a string (see [CE-JSON]).

Pfs

The list of product footprints that have been requested with the PF Request Event and that are accessible to the data recipient, encoded as an array of ProductFootprint in JSON.

Otherwise, the value of Pfs MUST be the empty JSON array.

6.8.4.3. PF Response Error Event syntax

The PF Response Error Event is defined as a CloudEvent event sent from a data owner to a data recipient after having received a PF Request Event from a data recipient and upon NOT successfully fulfilling the request.

The PF Response Event is defined as a JSON-encoded CloudEvent event with the following syntax:

{
  "type": "org.wbcsd.pathfinder.ProductFootprintRequest.Rejected.v1",
  "specversion": "1.0",
  "id": "EventId",
  "source": "...",
  "data": {
    "requestEventId": "ReqEventId",
    "error": ReqErrorResponse
  }
}

with

ReqErrorResponse

The error response that the data owner is sending to the data recipient to notify the data recipient that the request cannot be processed.

The value of ReqErrorResponse MUST be an error response (see § 6.9 Error responses).

6.9. Error responses

The actions Action GetFootprint, Action ListFootprints, and Action Events specify general error response handling.

This section specifies the shared HTTP error response handling across these actions.

Error responses are specified in detail such that data recipients can understand the cause of the error, and so that potentially host systems can react on and resolve errors automatically.

Note: Action Authenticate specifies its own error responses (see § 6.5.2 Response Syntax).

Whenever a host system returns an error response, it MUST send a HTTP response such that

• the HTTP Status Code equals the HTTP Status Code defined for the respective error response code (see Error Codes Table)

• with content type set to application/json, and

• with response body the error response

A error response is a JSON object with the following properties:

• code: a error response code encoded as a String

• message: a error message encoded as a String

A error response code is a value from column Error Response Code from the table below.

A error message is a human-readable error description. Example values are in column Example Message in the table below.

A host system MAY return error messages different from the table below, for instance localized values depending on a data recipient.

6.9.1. Error processing by a data recipient

A requesting data recipient MUST use the code property and potentially also the HTTP Status Code to differentiate between the different errors.

6.10. Examples

6.10.1. Example Action ListFootprints request and response

GET /2/footprints?limit=10 HTTP/2
host: api.pathfinder.sine.dev
authorization: Bearer [BearerToken]

HTTP/1.1 200 OK
date: Mon, 23 May 2022 19:33:16 GMT
content-type: application/json
content-length: 1831
server: Pathfinder
link: <https://api.pathfinder.sine.dev/2/footprints?limit=10&offset=10>; rel="next"

6.10.2. Example Error Response

GET /2/footprints HTTP/2
host: api.pathfinder.sine.dev

HTTP/1.1 403 Forbidden
date: Mon, 23 May 2022 19:33:16 GMT
content-type: application/json
content-length: 44
server: Pathfinder

Appendix A: License

Appendix B: Changelog

Version 2.0.1-20231026 (Oct 26, 2023)

Summary of changes:

1. clarification of the error responses of the Action Authenticate endpoint, plus addition of an example error response in line with [rfc6749]

Version 2.0.1-20230927 (Sep 27, 2023)

Summary of changes:

1. definition fixes to properties primaryDataShare and dqi to resolve a discrepancy with the latest version of the Pathfinder Framework: previously, the 2 properties were defined in a mutually-exclusive fashion (either one must be defined but NOT both) whereas the Pathfinder Framework Version 2.0 defines them as follows (Section 4.2.1, Page 39): Initially, companies shall calculate and report, as part of PCF data exchange, on at least one of the following metrics: [...]

2. addition of references to SI Units to data type DeclaredUnit

Version 2.0.1-20230720 (Jul 20, 2023)

Summary of changes:

1. clarification to specification of property fossilGhgEmissions, pCfExcludingBiogenic, pCfIncludingBiogenic, and biogenicCarbonWithdrawal

2. in addition, further clarfication on the bounds of the property biogenicCarbonWithdrawal which must be equal to 0 or less than 0

Version 2.0.1-20230629 (Jun 29, 2023)

Summary of changes:

1. clarify unit of properties fossilCarbonContent and biogenicCarbonContent: was declared as kg / declaredUnit and is now declared as kgC / declaredUunit

Version 2.0.1-20230627 (Jun 27, 2023)

This version fixes 5 definition incorrectness

1. property fossilCarbonContent: was incorrectly defined with unit kg of CO2e / declaredUnit. The unit is now defined as kg / declaredUnit

2. fix to the referencePeriod Filter Example

3. fixed typo in the definition of referencePeriodEnd

4. fixed definition of landManagementGhgEmissions: previously, it was incorrectly defined as a non-negative decimal

5. fixed definition of biogenicCarbonWithdrawal: previously, it was incorrectly defined as a non-negative decimal

In addition, this version:

1. clarifies in § 6.6 Action ListFootprints the semantics of the Filter processing being OPTIONAL by introducing section § 6.6.1 Filtering

2. clarifies that a host system must return HTTP error status codes if it does not implement the events endpoint (see § 6.8 Action Events)

3. clarified the PCF term definition

4. fixed linking to semantic versioning document

5. reworded referencePeriodStart and referencePeriodEnd

Version 2.0.1-20230522 (May 22, 2023)

This version fixes 1 definition incorrectness and includes 4 documentation improvements.

1. property biogenicCarbonContent: was incorrectly defined with unit kg of CO2e / declaredUnit. The unit is now defined as kg / declaredUnit

2. property status: minor documentation improvements

3. Action Action ListFootprints: minor documentation improvements

4. property biogenicAccountingMethodology: addition of an advisement

5. section § 4.3 Data Type: DataQualityIndicators is now referencing Table 9 of the Pathfinder Framework

Version 2.0.1-20230314 (Mar 14, 2023)

This version fixes 2 discrepancies between the Pathfinder Framework Version 2 and the data model in this specification.

1. property boundaryProcessesDescription: was incorrectly defined as optional in v2.0.0, and this typo is now corrected such that the property is correctly marked as mandatory in accordance with the Pathfinder Framework Version 2

2. update to definition of property primaryDataShare: it was marked as optional (O) and is now marked as O*. This update is in accordance with the Pathfinder Framework and the field’s previous (v2.0.0) semantics; i.e. no semantical update to the specification whatsoever

3. formatting fix to the definition of property productDescription

4. Updates to data type Assurance:

   1. documentation fix to definition of property coverage: was marked as mandatory (M) and is now marked as O in accordance with its definition and the Pathfinder Framework; i.e. no semantical update to the specification whatsoever

   2. addition of property assurance in accordance with the Pathfinder Framework

Version 2.0.0 (Feb 20, 2023)

Summary of the major changes and concepts added with this version:

1. update to Pathfinder Framework Version 2.0, including data model changes which are not backwards-compatible, including

   1. addition of data type DataQualityIndicators and Assurance to CarbonFootprint

2. event-based communication between host systems (§ 6.8 Action Events)

3. support for data model extensions (§ 4.5 Data Type: DataModelExtension)

4. life cycle management of a ProductFootprint (§ 5 Product Footprint Lifecycle)

Data Model Changes

Overview of the changes to the data model compared with the data model version 1.0.1:

• changes to data type ProductFootprint:

• properties validityPeriodStart and validityPeriodEnd: added

• life cycle properties precedingPfIds, status and statusComment: added

• addition of data type DataQualityIndicators to CarbonFootprint via property dqi

• addition of data type Assurance to CarbonFootprint via property assurance

• changes to data type CarbonFootprint:

• property characterizationFactors: added

• property exemptedEmissionsPercent: added

• property primaryDataShare: was mandatory is now optional

• property pCfExcludingBiogenic: added

• property pCfIncludingBiogenic: added

• property fossilCarbonContent: added

• property biogenicCarbonWithdrawal: added

• property biogenicAccountingMethodology: added

• property packagingEmissionsIncluded: added

• property exemptedEmissionsDescription: added

• property <{CarbonFootprint/packagingGhgEmissions}: added

• property uncertaintyAssessmentDescription: added

• property reportingPeriodStart: renamed to referencePeriodStart

• property reportingPeriodEnd: renamed to referencePeriodEnd

• property emissionFactorSources: renamed to secondaryEmissionFactorSources

• property aircraftGhgEmissions: added

• changes to data type BiogenicEmissions:

• all properties moved to CarbonFootprint and the data type removed fully, plus

• property landUseChangeGhgEmissions substituted with properties iLucGhgEmissions and dLucGhgEmissions

• property landUseEmissions renamed to landManagementGhgEmissions

• property otherEmissions renamed to otherBiogenicGhgEmissions

• data type CompanyId: added, including instructions on custom company codes

• changes to data type ProductId: addition of instructions (§ 4.21.2 ProductId based on CAS Registry Numbers, § 4.21.3 ProductId based on IUPAC InChi Code, § 4.21.1 Custom Product Ids (Product Codes))

API Changes

• Action ListFootprints:

  1. rename of filter HTTP query parameter filter to $filter

  2. introduce additional allowed $filter operators and properties:

     • Additional operators: eq, lt, le, gt, and, any

     • Additional properties: created, updated, productCategoryCpc, geographyCountry, referencePeriodStart, referencePeriodEnd, companyIds, productIds.

  3. Addition of alternative Action ListFootprints response HttpStatusCode 202, and pull-based request/response semantics

  4. pagination is now mandatory. See § 6.6.2 Pagination

• Action Events: section § 6.8 Action Events added

Version 1.0.1

The following changes have been applied for version 1.0.1

1. Addition of data type RegionOrSubregion, cleaning up the definition of property geographyRegionOrSubregion

2. Fix to the JSON representation specification in § 4.10.1 JSON Representation

3. Change to the minimum size of the set § 4.12 Data Type: ProductOrSectorSpecificRuleSet from 0 to 1, aligning with the overall specification.

4. Removal of unreferenced data type Boolean from the data model section

5. Rewording, simplified wording of chapter § 6.5 Action Authenticate

6. Addition of an authentication flow specification in chapter § 6.3 Authentication and Request Flows

7. Improved wording of request parameter Filter in section § 6.6.3 Request Syntax (HTTP/1.1)

8. Improved wording in section § 6.9 Error responses, specifically

   • addition of error response definition

   • improved specification of the error response JSON representation

   • consolidated specification of overall error response representation as a HTTP Response

   • improvements to previous subsection "List of error codes", plus merging into overall section § 6.9 Error responses

   • addition of list of example situations when an error response is returned

9. Addition of Section § 6.10.2 Example Error Response

10. Addition of term interoperable to section § 2 Terminology, plus linking to in respective sections

11. Addition of Terms UN geographic region and UN geographic subregion

12. Introduction of a new property table layout in section § 4.2 Data Type: CarbonFootprint and § 4.1 Data Type: ProductFootprint

13. Removal of data types PositiveDecimal, SpecVersionString, VersionInteger