Technical Specifications for PCF Data Exchange (3.0.0-20250217)

1. Introduction

This is the Draft Release of the PACT 3.0.0 Specifications, for consultation and feedback by the PACT Members.

This document is a work in progress and should not be used for conformance testing. Please refer to the latest stable version of the Technical Specifications for this.

For an overview of changes since the last version (2.3), see the Changelog

This document contains the necessary technical foundation for the PACT 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 PACT Methodology Version 3.0, see [PACT-METHODOLOGY].

1.1. Status of This Document

Comments regarding this document are welcome. Please file issues directly on GitHub, or send them to pact@wbcsd.org.

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

The technical specifications within this document are the result of consensus 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 (§ 7 Data Model) based on the PACT Methodology Version 3.0 and the definition of a HTTP REST API (§ 8 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 PACT Methodology;

• 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 PACT Network.

1.4. About PACT and the PACT Network

The PACT (previously 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 PACT Pathfinder Network 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.

PACT would also like to expressly thank the 40+ solutions which implemented V2 of the PACT Technical Specifications and became conformant during 2023 and 2024, resulting in significant learnings and feedback which is now incorporated in V3.

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 § 7.7 DataModelExtension

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

Data recipient

The company requesting and/or receiving PCF data from another company, using the technical means specified in this document.

Data owner

The company exchanging PCF data with another company, using the technical means specified in this document.

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).

OpenId Provider Configuration Document

A OpenId Provider Configuration Document document provided in accordance with [OPENID-CONNECT] Section 4

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.

PACT Methodology Version 3.0 (PACT Methodology)

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

PACT Network

An information network (previously Pathfinder Network) of and for companies 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 PACT Methodology.

Solution Provider

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

Solution

Any PACT-conformant software host system is called a solution.

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 § 8 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 § 8 HTTP REST API.

4. Exchanging Footprints

Note: This chapter is non-normative.

Achieving transparency in carbon emissions at the product level is challenging due to the complexity of global supply chains. This specification focuses on enabling transparency through a peer-to-peer PCF data exchange by specifying necessary aspects for achieving interoperability, such as the data model and API.

This chapter provides examples for inter-company business cases related to the exchange of PCFs, focusing on both asynchronous event processing and synchronous API calls.

4.1. Asynchronous Exchange

Exchanging PCF’s asynchronously requires both the data owner and the data recipient to run a PACT conformant host system, both sides being able to initiate communication to each other.

4.1.1. Requesting a PCF

Generally, the data recipient sends a RequestCreatedEvent event to the data owner. The data owner will try to fullfil this request and, after some time, send the a RequestFullfilledEvent event back to the recipient.

1. The data recipient authenticates with the data owner.

2. The data recipient sends the RequestCreatedEvent event to the data owner, including criteria specifying which PCF it wants to receive, like product ID, reference period or geography.

3. The data owner validates the incoming event, directly returning a HTTP 2xx success code if OK, or a 4xx status code indicating error.

4. Asynchronously, the data owner will create a PCF or find an existing relevant PCF.

5. The data owner will authenticate with the data recipient and send either a RequestFullfilledEvent back with the PCF or a RequestRejectedEvent if it can not produce the PCF.

6. TODO: something about retrying

4.1.2. Sending an updated PCF

At any time after a data owner has sent a PCF to the data recipient, the data owner can send an update, for example because a PCF was updated or deprecated, or a new PCF was published, see [#lifecycle].

In this case the data owner sends a PublishedEvent to the data recipient.

1. The data owner authenticates with the data recipient and sends a PublishedEvent with the updated or created PCF.

2. The data recipient should validate this incoming event and directly return a status code indicating succesful receipt (HTTP code 2xx) or an error (HTTP 4xx or 5xx).

Refer to § 8.7 Action Events for detailed request and response formats.

4.2. Synchronous retrieval

The synchronous part of te API allows for immediate retrieval of PCF’s. Refer to § 8.5 Action ListFootprints and § 8.6 Action GetFootprint for detailed request and response formats.

4.2.1. Getting multiple PCF’s

The ListFootprints action allows for directly retrieving multiple PCF’s. Starting from version 3.0, host systems must provide filtering on a minimum set of criteria.

1. The data recipient authenticates with the data owner.

2. The data recipient calls the /footprints endpoint, optionally providing a filter with search criteria and a limit to obtain a list of PCF’s.

3. After validating the request, the data owner returns a 2xx status code and the list of { } objects. On error the data owner returns a relevant HTTP error code. For details, see [#rest-api]

4.2.2. Getting a single PCF

A data-recipient can directly obtain a given PCF by it’s ID by calling GetFootprint.

1. The data recipient authenticates with the data owner.

2. The data recipient calls the /footprints/{id} endpoint, providing the PCF ID (in UUID format)

3. If found, the data owner returns the PCF in ProductFootprint and HTTP status code 200. If not found an 401 (Not found) status code will be returned.

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.

Starting with Version 3.0, any change to a Product Footprint will result in a new Product Footprint with a new ID. The previous Product Footprint will be marked as Deprecated.

5.2. Change Definition and Handling

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

After creation of a ProductFootprint this footprint MUST NOT be changed, EXCEPT for changing its status property to Deprecated

A ProductFootprint with status Deprecated MUST NOT be changed anymore.

5.2.1. Updating PCFs

Starting with Version 3.0, a change to any part of the footprint MUST result in a new footprint with a new id. The old id SHOULD be added to the PrecedingPfIds list to be able to track back to the previous version. The version number of this new PCF MUST always be 1 and the updated property always null. The old PCF MUST have its status set to Deprecated.

5.2.2. Deprecating PCFs

If a PCF becomes obsolete without being replaced, the status property of the PCF needs to be set to Deprecated.

5.2.3. Properties to Become Obsolete

Starting version 3.0, the statusComment is now obsolete and has been removed from the ProductFootprint. In future versions the deprecated properties version and updated will be removed.

5.2.4. Implementation Guidelines

1. Version 3.x MAY in its internal data model store the version and updated properties. Any incoming minor change will be accepted if incoming.version is higher than existing.version. The updated PCF will be stored, including version and updated properties.

2. Version 3.x MAY choose NOT to store version and updated properties. In that case, any incoming minor change will be accepted if incoming.updated is later than existing.created. The PCF will be stored, making sure the created date/time is set to the incoming updated date/time.

5.3. Validity Period

The validity period is the time interval during which the ProductFootprint is declared as valid for use by a receiving data recipient.

The validity period is OPTIONAL defined by the properties validityPeriodStart (including) and validityPeriodEnd (excluding).

If a validity period is specified, it is restricted to a time window between referencePeriodEnd and referencePeriodEnd + 3 years:

• If specified, validityPeriodStart MUST be greater than or equal to referencePeriodEnd.

• If validityPeriodEnd is specified it MUST be less than or equal to {CarbonFootprint/referencePeriodEnd}> + 3 years.

If no validity period is specified, the ProductFootprint is valid for 3 years starting with referencePeriodEnd.

6. Product Identification and Classification

To exchange PCF data between organizations, it is necessary to identify the related product or material. Given data owners and data recipients do not always (or often) use the same identification schemes, commonly and uniquely identifying the same product is a challenge - especially at scale. Given this situation, organizations must perform laborious and manual “mapping” exercises to map their identifier(s) for a product to the identify their supplier can understand.

This specification describes how the product ID URN (Uniform Resource Name) should be constructed in cases where no formal namespace for a given product identifier is defined.

This will not eliminate the need for a mapping process but will ease mapping identifiers with a common, easily understood structure. Further, this proposal ensures interoperability with industry-specific product identifiers.

We recognize there are existing relevant namespaces and corresponding URN syntax specifications. These can either be IANA-registered namespaces (like urn:ISBN) or widely used standards like urn:gtin. When product identification based on one or more of these standards is applicable, the corresponding namespaces should be used.

Similar to product identifiers, product classifiers ProductClassifications contain URN’s, using well-known namespaces when applicable, or a custom pact namespace if needed.

6.1. Product Identifier URN’s

urn:namespace:namespace-specific-string

In determining which URN namespace and corresponding syntax to use, the data owner SHOULD follow the reasoning below:

1. If an IANA-registered URN namespace exists and is applicable, this SHOULD be used. See IANA Registered Namespaces for existing specifications, like ISBN.

2. If a widely used URN schema exists and is applicable, this SHOULD be used, for example GTIN product identifiers.

3. If the data owner wishes to use a product identifier for which an existing URN specification does not exist, the data owner SHOULD use the following format:

   urn:pact:$domain-of-issuer$:$identifier-type$:$id$
   

   • urn:pact: is the fixed sub-string to identify the URN namespace.

   • $domain-of-issuer$ is the fully qualified domain name [RFC1035] of the organization issuing the identifier. Ideally the fully qualified domain points to the product specification. For example: catalog.mycompany.com

   • $identifier-type$ defines the kind of product identifier being specified. This brings clarity to the recipient to understand what kind of identifier is provided.

   • $id$ is the actual id of the product within this context. This can be any string uniquely identifying the product.

   The following $identifier-type$ values are recommended.

   $identifier-type$	Description	Notes
   product-id	Specifies a product id from a third-party organization, standard, etc.	Use this identifier-type when no other, more specific one is applicable.
   buyer-id	Specifies a product id created by the buyer, aka data recipient.	This is the equivalent of "buyer-assigned" as referenced in Tech Specs V2.
   supplier-id	Specifies a product id created by the supplier, aka data owner.	This is the equivalent of "vendor-assigned" as referenced in Tech Specs V2.

   This is a non-exhaustive list of $identifier-type$. This set MAY be extended in minor versions of the standard release. Organizations may contact PACT to propose additional $identifier-type$ for consideration to be added as recommended industry-agnostic identifiers.

   Organizations and industry initiatives are encouraged to define the relevant $identifier-type$ for products within their industry separately.

6.1.1. Examples

Below is a list of examples of productIds as used in the ProductFootprint data type clarifying the use of well-known and custom URN namespaces for identifying products.

["urn:pact:sample.com:product-id:44055-9c05bc35-68f8"]
["urn:pact:sample-buyer.com:buyer-id:103403453"]
["urn:pact:sample-supplier.com:supplier-id:1234"]

["urn:isbn:978-951-0-18435-6"]

["urn:gtin:4712345060507"]

["urn:uuid:69585GB6-56T9-6958-E526-6FDGZJHU1326"]

["urn:pact:sigmaaldrich.com:supplier-id:14021",
"urn:pact:cas.org:substance-number:13463-67-7",
"urn:pact:iupac.org:substance-name:dioxotitanium",
"urn:pact:inchi-trust.org:substance-id:1S,/2O.Ti",
"urn:pact:inchi-trust.org:substance-key:
GWEVSGVZZGPLCZ-UHFFFAOYSA-N"]

6.2. Product Classification URN’s

Similar to ProductIds a ProductClassification MUST be a URN as specified in [RFC8141]:

urn:namespace:namespace-specific-string

In determining which URN namespace and corresponding syntax to use, the data owner SHOULD follow the reasoning below:

1. If an IANA-registered URN namespace exists and is applicable, this SHOULD be used. See IANA Registered Namespaces for existing specifications. Example: 'urn:iso'

2. If a widely used URN namespace exists and is applicable, this SHOULD be used.

3. If the data owner wishes to use a product identifier for which an existing URN specification does not exist, the data owner SHOULD use the following format:

   urn:pact:$domain-of-issuer$:$type$:$value$

   • urn:pact: is the fixed sub-string to identify the URN Namespace. Based on feedback from the community we propose the use of pact as the recommended namespace.

   • $domain-of-issuer$ is the fully qualified domain name of the organization issuing the category identifier. The issuer of the code can be an organization, company or industry initiative. Example: categories.mycompany.com

   • $type$ defines the kind of product category or classification being specified. This brings clarity to the recipient to understand what kind of classification is provided.

6.2.1. Examples

["urn:pact:cas.org:substance-number:13463-67-7"]

["urn:pact:inchi-trust.org:substance-id:$INCHI-ID$"]

"urn:pact:catalog.company.com:category-id:550010"

"urn:cpc:0151"

"urn:unspsc:43211507"

"urn:eclass:28070000"

"urn:iso:std:iso:4217"

These namespaces allow systems and standards to consistently identify and categorize products, making them useful in a variety of domains like supply chain management, retail, industrial procurement, and publication. If you’re working with a specific product categorization system, you may find these URNs particularly relevant for classification or reference purposes.

7. Data Model

7.1. Introduction

This section specifies a data model for product footprints conforming with the PACT Methodology Version 3.

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.

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

2. CarbonFootprint: contains information related to the carbon footprint of a product.

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

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.

7.1.1. OpenAPI Schema

The Data model and the REST API are defined by the OpenAPI specification at https://specs.carbon-transparency.org/. All data types described below are based on this schema.

7.2. Basic Types

The following basic types are used in the data model:

"Sample string"

"{91715e5e-fd0b-4d1c-8fab-76290c46e6ed}"

"urn:gtin:5695872369587"

"12.3456",
"-9876.5432102"
"1.2345e+6"

123,
-456

"2024-04-23T18:25:43.511Z"

true

7.3. Qualifiers

Types can have the following qualifiers:

7.4. Undefined Properties

In a JSON object, a property is deemed undefined if it is either not present in the object or explicitly set to null. For example:

{
  "property1": "value1",
  "property2": null
}

In this example, property2 is considered undefined. Also, any property not present in the object, for example property3 is also considered undefined.

7.5. ProductFootprint

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 § 8 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 § 7.7 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).

7.5.1. Properties

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

"specVersion": "3.0.0"

"precedingPfIds": [
  "f4b1225a-bd44-4c8e-861d-079e4e1dfd69",
  "079e425a-464f-528d-341d-4a944a1dfd70"
]

"created": "2024-10-31T00:00:00Z"

"status": "Active"

"companyIds": [
  "urn:company:example:company1"
]

"productClassifications": [
  "urn:pact:productclassification:un-cpc:1234"
]

7.6. CarbonFootprint

7.6.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 PACT Methodology section 6.1.2.1)

2. Geography: further set by the properties geographyRegionOrSubregion, geographyCountry, and geographyCountrySubdivision (see PACT Methodology 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.

7.6.2. Properties

"ipccCharacterizationFactors": [
  "AR6"
]

"crossSectoralStandards": [
  "ISO14067",
  "PACT-3.0"
]

"productOrSectorSpecificRules": [
  {
    "operator": "PEF",
    "ruleNames": [
      "PEF 1.0",
      "PEF 2.0"
    ]
  },
  {
    "operator": "PCR",
    "ruleNames": [
      "PCR-A"
    ]
  }
]

"geographyRegionOrSubregion": "Eastern Asia"

"geographyCountry": "US"

"geographyCountrySubdivision": "US-CA"

"secondaryEmissionFactorSources": [
  {
    "name": "ecoinvent",
    "version": "3.7"
  }
]

7.7. DataModelExtension

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

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

7.7.1. Properties

7.8. ProductOrSectorSpecificRule

{
  "operator": "PEF",
  "ruleNames": [
    "PEF 1.0",
    "Other"
  ]
}

7.8.1. Properties

"operator": "PEF"

"ruleNames": [
  "PEF 1.0",
  "PEF 2.0"
]

7.9. EmissionFactorSource

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

7.9.1. Properties

"name": "ecoinvent"

"version": "3.9.1"

7.10. DataQualityIndicators

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

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

7.10.1. Properties

7.11. Verification

{
  "coverage": "PCF system",
  "boundary": "Cradle-to-Gate"
  "providerName": "My Auditor",
  "completedAt": "2022-12-08T14:47:32Z"
  "standardName": "ISO 14044"
}

7.11.1. Properties

8. HTTP REST API

8.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.

8.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 (§ 8 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.

8.2.1. Minimum requirements ## {#api-requirements}

A host system MUST implement the actions

• Action Authenticate

• Action ListFootprints

• Action GetFootprint

• Action Events.

The host system MUST make its footprints available to the data recipient through both Action ListFootprints AND Action Event.

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

A host system SHOULD offer an OpenId Provider Configuration Document as specified in [OPENID-CONNECT].

A host system MUST offer all actions under the same Hostname and Subpath except for the token endpoint (Action Authenticate and the endpoint returned from the OpenId Provider Configuration Document).

A host system CAN offer the OpenId Provider Configuration Document and Action Authenticate under AuthHostname and AuthSubpath which are different from Hostname and Subpath.

If a host system does not offer an OpenId Provider Configuration Document, data recipients MUST assume that Action Authenticate is offered under AuthHostname/AuthSubpath/auth/token (see § 8.3 Authentication Flow).

In case of succesful retrieval or creation of the PCF(s), The host system of the data owner MUST send back the 1 or more product footprints in a single event message to the data requester.

8.2.2. 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 PACT Methodology
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.

8.3. Authentication Flow

A host system requires a data recipient to first authenticate before successfully calling an Action (such as Action ListFootprints or Action Events). The data recipient MUST perform the authentication flow:

1. data recipient attempting to perform the OpenId Connect-based flow, by

   1. retrieving and validating the OpenId Provider Configuration Document of the host system (see [OPENID-CONNECT]), and then

   2. using as AuthEndpoint the value of the token_endpoint property of the OpenId Provider Configuration Document

2. otherwise, data recipient using AuthHostname/AuthSubpath/auth/token as the AuthEndpoint in the next step.

3. data recipient retrieving the access token from AuthEndpoint (see § 8.4.1 Request Syntax (HTTP/1.1)).

Note: The authentication flow is defined such that a Version 3.0.0 data recipient can authenticate against host versions irrespective of their support for OpenID-Connect.

Once the authentication flow is complete, the data recipient can call the other 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.

8.4. 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.

8.4.1. Request Syntax (HTTP/1.1)

For reasons of backwards-compatibility with data recipients implementing the Version 2.0 authentication flow only, Host systems MUST offer this action under path AuthSubpath/auth/token and hostname AuthHostname.

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

In addition, if a host system supports OpenId Connect, the host system CAN offer and implement this Action under a second URL, and set this URL as the value of token_endpoint of the OpenId Provider Configuration Document.

POST AuthEndpoint HTTP/1.1
accept: application/json
content-type: application/x-www-form-urlencoded
authorization: Basic BasicAuth
content-length: ContentLength

AuthBody

With Request parameters:

AuthEndpoint

The endpoint to request an access token after discovering the value by performing the authentication flow.

AuthSubpath:

If a host system uses a relative subpath dedicated to serving an OpenId Provider Configuration Document and creating an access token, then the requesting data recipient MUST use this subpath.

AuthHostname

The requesting data recipient MUST use the domain name of the host system dedicated to serving an OpenId Provider Configuration Document and creating an access token.

BasicAuth

See [rfc6749] Section 4.4.2

AuthBody

See [rfc6749] Section 4.4

ContentLength

The length of the Body. See [rfc9112].

8.4.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 (containing an access token), or RFC 6749 Section 5.2 otherwise. See § 8.3 Authentication Flow for further details

8.4.2.1. Example Successful Response

Example AuthResponseBody for a successful authenticate call:

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

8.4.2.2. Example Error Response

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

HTTP/1.1 400 Bad Request
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.

8.5. 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.

8.5.1. Filtering

Filtering on minimal set of criteria MUST be supported by Host systems.

Note: This MUST be the same set of criteria that can be used with PF Request Event

Note: Optional filtering specified in version 2.2+ (based on OData4) is NOW DEPRECATED.

productId array(string)

If present, MUST be 1 or more product ID’s. Will return all footprints which have a corresponding ID in their productIds attribute. Note that a footprint itself can also have multiple product IDs.

companyId array(string)

If present, MUST be 1 or more company ID’s. Will return all footprints with corresponding id’s in the companyIds attribute.

geography array(string)

if present, MUST be 1 or more geographic specifiers. Values specified can denote geographicRegion or geographyCountry or geographyCountrySubdivision. Will return all footprints within the specified geography(s)

classification array(string)

if present, MUST be 1 or more product classifications. Will return all footprints with corresponding values in the productClassifications attribute. Note that a footprint itself can have multiple classifications.

validOn (date-string)

if present, MUST match all PCF’s which where valid on the date specified: footprint.validityPeriodBegin <= validOn AND validFrom <= footprint.validityPeriodEnd

validAfter (date-string)

if present, MUST match PCF’s whith validAfter < footprint.validityPeriodBegin

validBefore (date-string)

if present, MUST match PCF’s whith validBefore > footprint.validityPeriodEnd

status (string)

If Present, MUST be either be "Active" or "Deprecated"

8.5.1.1. Extensions

Implementors MAY offer additional criteria to filter on. In doing so, both the sync (ListFootprints) AND async (Events/ProductFootprintRequest.Created) methods MUST implement these criteria.

Additional critera MUST be named x- - . For example, adding functionality to search for product footprints based on an invoice-id, an software provider could choose to use:

x-atq-invoice-id

This will enable queries like .../footprint/?x-atq-invoice-id=12345&geography=FR

8.5.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 § 8.3 Authentication Flow)

   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

8.5.3. Request Syntax (HTTP/1.1)

GET Subpath/3/footprints?[Criteria]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 § 8.3 Authentication Flow

Criteria

see Filtering for the parameters which can be specified.

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.

8.5.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 access token is valid, but the client does not have the necessary permissions to access the requested ProductFootprints, the host system MUST return 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, the body SHOULD be an error response with code BadRequest.

8.6. 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.

8.6.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.

8.6.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 access token is valid, but the client does not have the necessary permissions to access the requested ProductFootprint, the host system MUST return an error response with code AccessDenied.

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

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

In all other cases, the body SHOULD be an error response with code BadRequest.

8.7. 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 § 8.7.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 § 8.7.4 Asynchronous request and retrieval of Product Footprints).

A host system SHOULD only accept events after authentication (see § 8.3 Authentication Flow).

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

Support for Action Events is MANDATORY.

8.7.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 § 8.7.3 Notification of data recipients on Product Footprint updates and § 8.7.4 Asynchronous request and retrieval of Product Footprints.

8.7.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 § 8.8 Error responses).

8.7.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.

8.7.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.

8.7.4.1. PF Request Event syntax

The PF Request Event MUST be a CloudEvent event sent from a data recipient to a data owner containing a set of criteria that reference the product for wich the PCF is being requested.

Note: The ProductFootprintFragment in version 2.x is OBSOLETE.

Note: This MUST be the same set of criteria that can be used with Action ListFootprints

Note: this specification does not yet specify the processing requirements of a host system upon receiving such an event. This means the host system can e.g. ignore 1 or more properties, it might not accept specific patterns of requests (for instance it might support querying by reference period but not by geography), etc.

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": "2025-01-31T17:31:00Z",
  "data": {
    "productId": ["urn:pact:product-id:1234"]
    "companyId": ["urn:companyId"]
    "geography": ["DE"]
    "classification": ["urn:cpc:9585"]
    "validOn": "2025-02-01T00:00:00Z",
    "validAfter": "2025-02-01T00:00:00Z",
    "validBefore": "2025-02-01T00:00:00Z",
    "status": "Active",
    "comment": PFRequestComment
  }
}

with

productId array(string)

If present, MUST be 1 or more product ID’s. Will return all footprints which have a corresponding ID in their productIds attribute. Note that a footprint itself can also have multiple product IDs.

companyId array(string)

If present, MUST be 1 or more company ID’s. Will return all footprints with corresponding id’s in the companyIds attribute.

geography array(string)

if present, MUST be 1 or more geographic specifiers. Values specified can denote geographicRegion or geographyCountry or geographyCountrySubdivision. Will return all footprints within the specified geography(s)

classification array(string)

if present, MUST be 1 or more product classifications. Will return all footprints with corresponding values in the productClassifications attribute. Note that a footprint itself can have multiple classifications.

validOn (date-string)

if present, MUST match all PCF’s which where valid on the date specified: footprint.validityPeriodBegin <= validOn AND validFrom <= footprint.validityPeriodEnd

validAfter (date-string)

if present, MUST match PCF’s whith validAfter < footprint.validityPeriodBegin

validBefore (date-string)

if present, MUST match PCF’s whith validBefore > footprint.validityPeriodEnd

status (string)

If Present, MUST be either be "Active" or "Deprecated"

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.

8.7.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.

8.7.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 § 8.8 Error responses).

8.8. 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 § 8.4.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.

{
  "message": "Access Denied",
  "code": "AccessDenied"
}

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

8.8.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.

8.9. Examples

8.9.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"

{
  "data": [
    {
      "id": "91715e5e-fd0b-4d1c-8fab-76290c46e6ed",
      "specVersion": "3.0.0",
      "version": 1,
      "created": "2022-03-01T09:32:20Z",
      "status": "Active",
      "validityPeriodStart": "2022-03-01T09:32:20Z",
      "validityPeriodEnd": "2024-12-31T00:00:00Z",
      "companyName": "My Corp",
      "companyIds": [
        "urn:uuid:69585GB6-56T9-6958-E526-6FDGZJHU1326",
        "urn:epc:id:sgln:562958.00000.4"
      ],
      "productDescription": "Bio-Ethanol 98%, corn feedstock (bulk - no packaging)",
      "productIds": ["urn:gtin:5695872369587"],
      "productClassifications": ["urn:pact:productclassification:un-cpc:1234"],
      "productNameCompany": "Green Ethanol",
      "comment": "",
      "pcf": {
        "declaredUnitOfMeasurement": "liter",
        "declaredUnitAmount": "1",
        "productMassPerDeclaredUnit": "0.879",
        "pcfExcludingBiogenicCO2Withdrawal": "1.85",
        "pcfIncludingBiogenicCO2Withdrawal": "1.63",
        "fossilGhgEmissions": "1.5",
        "fossilCarbonContent": "0",
        "biogenicCarbonContent": "0.41",
        "landManagementBiogenicCO2Emissions": "0.6",
        "landManagementBiogenicCO2Removals": "-0.4",
        "biogenicCO2Withdrawal": "-1.5",
        "aircraftGhgEmissions": "0.2",
        "ipccCharacterizationFactors": ["AR6"],
        "crossSectoralStandards": [
          "GHGP-Product",
          "ISO14067"
        ],
        "productOrSectorSpecificRules": [
          {
            "operator": "Other",
            "ruleNames": [
              "The Product Carbon Footprint Guideline for the Chemical Industry, v.2.0"
            ],
            "otherOperatorName": "Tfs"
          }
        ],
        "biogenicAccountingMethodology": "GHPG",
        "boundaryProcessesDescription": "1) Material acquisition and preprocessing, including growth of corn 2) Production: fuel consumption, electricity consumption, water consumption, process-generated direct emissions 3) Distribution and storage: transportation of the finished product from manufacturing site to storage site",
        "referencePeriodStart": "2021-01-01T00:00:00Z",
        "referencePeriodEnd": "2022-01-01T00:00:00Z",
        "geographyRegionOrSubregion": "Western Europe",
        "secondaryEmissionFactorSources": [
          {
            "name": "Ecoinvent",
            "version": "3.1"
          }
        ],
        "exemptedEmissionsPercent": "0",
        "exemptedEmissionsDescription": "",
        "allocationRulesDescription": "Using mass allocation following the product specific rule as per PACT Framework decision-making tree",
        "primaryDataShare": "12.9",
        "dqi": {
          "technologicalDQR": "1.6",
          "temporalDQR": "2.6",
          "geographicalDQR": "1.8"
        },
        "verification": {
          "providerName": ""
        }
      },
      "extensions": [
        {
          "specVersion": "3.0.0",
          "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"
          }
        }
      ]
    }
  ]
}

{
  "data": []
}

8.9.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

{
  "message": "Access Denied",
  "code": "AccessDenied"
}

8.9.3. Example PF Request and Response Events

Example PF Request Event:

POST Subpath/2/events HTTP/1.1
host: api.pathfinder.sine.dev
authorization: Bearer [BearerToken]
content-type: application/cloudevents+json; charset=UTF-8

{
  "type": "org.wbcsd.pathfinder.ProductFootprintRequest.Created.v1",
  "specversion": "1.0",
  "id": "848dcf00-2c18-400d-bcb8-11e45bbf7ebd",
  "source": "//RequesterEventHostname/EventSubpath",
  "time": "2023-11-06T16:23:00Z",
  "data": {
      "pf": {
          "productIds": [
              "urn:gtin:4712345060507"
          ]
      },
      "comment": "Please provide current PCF value."
  }
}

HTTP/1.1 200 OK
content-length: 0

POST Subpath/2/events HTTP/1.1
host: api.pathfinder.sine.dev
authorization: Bearer [BearerToken]
content-type: application/cloudevents+json; charset=UTF-8

{
  "type": "org.wbcsd.pathfinder.ProductFootprintRequest.Fulfilled.v1",
  "specversion": "1.0",
  "id": "5afe8fbf-0ea9-477c-a1df-2d3c95f7eec0",
  "source": "//ProviderEventHostname/EventSubpath",
  "time": "2023-11-08T13:26:00Z",
  "data": {
    "requestEventId": "848dcf00-2c18-400d-bcb8-11e45bbf7ebd",
    "pfs": [
      {
        "id": "91715e5e-fd0b-4d1c-8fab-76290c46e6ed",
        "specVersion": "3.0.0",
        "version": 1,
        "created": "2022-03-01T09:32:20Z",
        "status": "Active",
        "validityPeriodStart": "2022-03-01T09:32:20Z",
        "validityPeriodEnd": "2024-12-31T00:00:00Z",
        "companyName": "My Corp",
        "companyIds": [
          "urn:uuid:69585GB6-56T9-6958-E526-6FDGZJHU1326",
          "urn:epc:id:sgln:562958.00000.4"
        ],
        "productDescription": "Bio-Ethanol 98%, corn feedstock (bulk - no packaging)",
        "productIds": ["urn:gtin:5695872369587"],
        "productClassifications": ["urn:pact:productclassification:un-cpc:1234"],
        "productNameCompany": "Green Ethanol",
        "comment": "",
        "pcf": {
          "declaredUnitOfMeasurement": "liter",
          "declaredUnitAmount": "1",
          "productMassPerDeclaredUnit": "0.879",
          "pcfExcludingBiogenicCO2Withdrawal": "1.85",
          "pcfIncludingBiogenicCO2Withdrawal": "1.63",
          "fossilGhgEmissions": "1.5",
          "fossilCarbonContent": "0",
          "biogenicCarbonContent": "0.41",
          "landManagementBiogenicCO2Emissions": "0.6",
          "landManagementBiogenicCO2Removals": "-0.4",
          "biogenicCO2Withdrawal": "-1.5",
          "aircraftGhgEmissions": "0.2",
          "ipccCharacterizationFactors": ["AR6"],
            "crossSectoralStandards": [
            "GHGP-Product",
            "ISO14067"
          ],
          "productOrSectorSpecificRules": [
            {
              "operator": "Other",
              "ruleNames": [
                "The Product Carbon Footprint Guideline for the Chemical Industry, v.2.0"
              ],
              "otherOperatorName": "Tfs"
            }
          ],
          "biogenicAccountingMethodology": "GHPG",
          "boundaryProcessesDescription": "1) Material acquisition and preprocessing, including growth of corn 2) Production: fuel consumption, electricity consumption, water consumption, process-generated direct emissions 3) Distribution and storage: transportation of the finished product from manufacturing site to storage site",
          "referencePeriodStart": "2021-01-01T00:00:00Z",
          "referencePeriodEnd": "2022-01-01T00:00:00Z",
          "geographyRegionOrSubregion": "Western Europe",
          "secondaryEmissionFactorSources": [
            {
              "name": "Ecoinvent",
              "version": "3.1"
            }
          ],
          "exemptedEmissionsPercent": "0",
          "exemptedEmissionsDescription": "",
          "allocationRulesDescription": "Using mass allocation following the product specific rule as per PACT Framework decision-making tree",
          "primaryDataShare": "12.9",
          "dqi": {
            "technologicalDQR": "1.6",
            "temporalDQR": "2.6",
            "geographicalDQR": "1.8"
          },
          "verification": {
            "providerName": ""
          }
        },
        "extensions": [
          {
            "specVersion": "3.0.0",
            "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"
            }
          }
        ]
      }
    ]
  }
}

HTTP/1.1 200 OK
content-length: 0

8.9.4. Example Action GetFootprint request and response

GET /2/footprint/91715e5e-fd0b-4d1c-8fab-76290c46e6ed 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

{
  "data": {
    "id": "91715e5e-fd0b-4d1c-8fab-76290c46e6ed",
    "specVersion": "3.0.0",
    "version": 1,
    "created": "2022-03-01T09:32:20Z",
    "status": "Active",
    "validityPeriodStart": "2022-03-01T09:32:20Z",
    "validityPeriodEnd": "2024-12-31T00:00:00Z",
    "companyName": "My Corp",
    "companyIds": [
      "urn:uuid:69585GB6-56T9-6958-E526-6FDGZJHU1326",
      "urn:epc:id:sgln:562958.00000.4"
    ],
    "productDescription": "Bio-Ethanol 98%, corn feedstock (bulk - no packaging)",
    "productIds": ["urn:gtin:5695872369587"],
    "productClassifications": ["urn:pact:productclassification:un-cpc:1234"],
    "productNameCompany": "Green Ethanol",
    "comment": "",
    "pcf": {
      "declaredUnitOfMeasurement": "liter",
      "declaredUnitAmount": "1",
      "productMassPerDeclaredUnit": "0.879",
      "pcfExcludingBiogenicCO2Withdrawal": "1.85",
      "pcfIncludingBiogenicCO2Withdrawal": "1.63",
      "fossilGhgEmissions": "1.5",
      "fossilCarbonContent": "0",
      "biogenicCarbonContent": "0.41",
      "landManagementBiogenicCO2Emissions": "0.6",
      "landManagementBiogenicCO2Removals": "-0.4",
      "biogenicCO2Withdrawal": "-1.5",
      "aircraftGhgEmissions": "0.2",
      "ipccCharacterizationFactors": ["AR6"],
      "crossSectoralStandards": [
        "GHGP-Product",
        "ISO14067"
      ],
      "productOrSectorSpecificRules": [
        {
          "operator": "Other",
          "ruleNames": [
            "The Product Carbon Footprint Guideline for the Chemical Industry, v.2.0"
          ],
          "otherOperatorName": "Tfs"
        }
      ],
      "biogenicAccountingMethodology": "GHPG",
      "boundaryProcessesDescription": "1) Material acquisition and preprocessing, including growth of corn 2) Production: fuel consumption, electricity consumption, water consumption, process-generated direct emissions 3) Distribution and storage: transportation of the finished product from manufacturing site to storage site",
      "referencePeriodStart": "2021-01-01T00:00:00Z",
      "referencePeriodEnd": "2022-01-01T00:00:00Z",
      "geographyRegionOrSubregion": "Western Europe",
      "secondaryEmissionFactorSources": [
        {
          "name": "Ecoinvent",
          "version": "3.1"
        }
      ],
      "exemptedEmissionsPercent": "0",
      "exemptedEmissionsDescription": "",
      "allocationRulesDescription": "Using mass allocation following the product specific rule as per PACT Framework decision-making tree",
      "primaryDataShare": "12.9",
      "dqi": {
        "technologicalDQR": "1.6",
        "temporalDQR": "2.6",
        "geographicalDQR": "1.8"
      },
      "verification": {
        "providerName": ""
      }
    },
    "extensions": [
      {
        "specVersion": "3.0.0",
        "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"
        }
      }
    ]
  }
}

Appendix A: License

1. Definitions.

1.1 "Database Rights" means, to the extent any content in the Licensed Material is subject to any sui generis database right under any applicable law, the rights to extract, reuse, reproduce, and Share all or a substantial portion of the content subject to such database right.

1.2 "Derivative" means any work or other creation that is a derivative work or otherwise derived from, based on, or including or using the Licensed Material, or any information or content thereof, in whatever form, format, or medium, now known or becoming known in the future.

1.3 "Licensed Rights" means any copyrights (including exclusive rights of reproduction, performance, display, creation of derivative works, and distribution), and any Database Rights, in the Licensed Material anywhere in the world owned by Licensor that Licensor has the right to license. Licensed Rights do not include (i) any intellectual property or other rights other than copyrights and Database Rights (including, without limitation, any rights in, to, or under any patent, patent application, trademark, service mark, trade dress, name, domain name, trade secret, or other intellectual property right anywhere in the world), (ii) any rights of integrity or attribution or other moral rights anywhere in the world, (iii) any rights to assert or enforce any copyrights or Database Rights against any other person, including, without limitation, in case of any infringement or violation, or to assert or collect any remedy therefor, and (iv) any copyrights or Database Rights in any subject matter other than the Licensed Material.

1.4 "Licensor" means World Business Council for Sustainable Development.

1.5 "Modified Version" means any copy or version of the Licensed Material that includes any alteration of, editing of, deletion from, addition or supplement to, or change or redaction of, or any variation of any content or information of, the Licensed Material, in whatever form, format, or medium, now known or becoming known in the future.

1.6 "Non-Commercially" means without the primary intent for or directed towards commercial advantage or monetary compensation.

1.7 "Reproduction" means an exact reproduction and copy of the Licensed Material as a whole or of any Translation released by Licensor under this License, without any alteration, edits, deletions, additions, supplements, changes, or redactions, and including, for the avoidance of doubt, this License. A Modified Version is not a Reproduction.

1.8 "Separate Derivative" means any Derivative that does not consist of or include a Reproduction, any Modified Version, or any Translation, or a part of a Reproduction, Modified Version, or Translation that is by itself the subject of Licensed Rights. An example of a Separate Derivative is a software program, course, written material, or program that uses or implements the information included in the Licensed Material without including, displaying, or performing the Licensed Material, any Modified Version, or any Translation, or any portion thereof.

1.9 "Share" means to provide, by any means or process, including by distribution of a copy, reproduction, public display, public performance, dissemination, communication, or importation, or to make available for access on a website or otherwise, to any other person as a member of the public

1.10 "Translation" means any translation of the Licensed Material as a whole (and not only a part thereof) that into any language other than English that reasonably accurately reflects the content of the Licensed Material in such other language.

1.11 "Use" means the practice or exercise of any of the Licensed Rights

2. License.

2.1 Subject to the terms and conditions of this License, Licensor hereby grants User during the Term (as defined in Section 6.1), solely under the Licensed Rights, a non-exclusive, worldwide, royalty-free, non-sublicensable, non-transferable, irrevocable license to Use the Licensed Material solely to: a. reproduce, but not Share (other than as permitted under Section 2.1(c)), the Licensed Material or any part thereof; b. create, but not Share (other than as permitted under Section 2.1(d)), any Derivative; c. Share (subject to compliance with Section 3.1) any Reproduction but only Non-Commercially; d. Share (subject to compliance with Section 3.2) any Separate Derivative, and create from such Separate Derivative any further Separate Derivatives and Share such further Separate Derivatives, all whether Non-Commercially or commercially.

2.2 If User Shares a Reproduction under Section 2.1(c) to another person, User automatically grants such other person an offer from Licensor to Use such Reproduction under this License, and such other person shall be deemed to accept and be subject to this License (and be a User under this License) once such other person make any Use of the Licensed Material or any part thereof. Other than this License, User may not impose any limitations, restrictions (technical, legal, or otherwise), payment, terms, conditions, or requirement of any kind on any such other person related to the access to or Use of such Reproduction under this License.

2.3 User shall make any User and exercise any of the Licensed Rights solely in accordance and compliance with all applicable law, and User shall not infringe any intellectual property right of any third party and/or misappropriate any information or intellectual property of any third party.

3. Attribution.

3.1 If User Shares any Reproduction under Section 2.1(c), User must retain, and not change, obstruct, or obscure in such Reproduction, the following information:

(i) identification of Licensor as the owner or rightholder of the Licensed Rights in the Licensed Material, and the name of any creator(s) of the Licensed Material identified herein; (ii) the copyright notice in this Licensed Material; (iii) the full text of this License.

3.2 If User Shares a Separate Derivative under Section 2.1(d), User must include a written notice in such Separate Derivative reasonably visible to any user of such Separate Derivative that:

(i) identifies the Licensed Material and such Separate Derivative as a derivative work or otherwise derived from, based on, or including or using the Licensed Material; (ii) identifies Licensor as the owner or rightholder of the Licensed Rights in the Licensed Material, and the name of any creator(s) of the Licensed Materials identified herein; (iii) reproduces exactly and in full Section 5 (Disclaimer of Warranties and Limitation of Liability).

3.3 Upon Licensor’s request, User shall remove or modify any of the information required by Section 3.1 or Section 3.2, as applicable, with regard to any Reproduction or Separate Derivative Shared after such request as reasonably practicable.

3.4 Nothing in this License constitutes or shall be construed to be, or shall imply, that User is, or User’s use of the Licensed Material in any way is, connected with, or sponsored, endorsed, or granted official status by, Licensor or any other person associated with Licensor or to whom attribution is to be given under Section 3.1 or Section 3.2.

4. Ownership.

4.1 In connection with this License, and as between Licensor and User, Licensor is and shall remain the sole owner of all rights, title, and interest in and to any and all of the Licensed Rights and the Licensed Material.

4.2 Licensor does not, and shall not be deemed to, assign, transfer, or convey any right, title, or interest in or to any Licensed Right or any other intellectual property or intellectual property right, or grant any license (other than the express license set forth in Section 2.1), lien, option, or claim in or to any Licensed Right or any other intellectual property or intellectual property right.

4.3 Nothing in this License shall prevent User from owning any intellectual property rights in or to any Derivative created by User under and in accordance with the license in Section 2.1, subject to Licensor’s continued ownership and rights in and to the Licensed Rights and Licensed Material. A Derivative does not give, and shall not be deemed to give, User any greater rights in or to any Licensed Rights or Licensed Material, or any right to Use, other than as expressly set forth in Section 2.1.

4.4 Licensor is in no way limited or restricted license, exercise, or exploit any of the Licensed Rights under any other terms or agreements, commercially or Non-Commercially, or to assign, transfer, or convey any of the Licensed Rights, all as decided by Licensor in its sole discretion.

5. Disclaimer of Warranties and Limitation of Liability.

5.1 Licensor offers, provides, makes available, and licenses the Licensed Material, and grants the license and Licensed Rights, "as is" and "as available" without any representations or warranties, express or implied. Licensor hereby disclaims all representations and warranties, express, implied, statutory, or otherwise, under any law, including, without limitation, all representations and warranties of title, merchantability, fitness for a particular purpose, non-infringement, absence of latent or other defects, accuracy, or the presence or absence of errors, whether or not known or discoverable. Where disclaimers of warranties are limited by applicable law, this disclaimer applies to the greatest extent not limited by such applicable law.

5.2 In no event will Licensor be liable to User or any other person, under contract, negligence, willful misconduct, other tort, property, intellectual property, or other cause or legal theory any legal theory or otherwise, for any direct, indirect, special, incidental, consequential, punitive, exemplary, liquidated, or other losses, costs, expenses, attorneys' or legal fees or costs, or damages of any kind anywhere, under any law, arising or related to this License, any Licensed Right, the Licensed Material, any Derivative, and/or any part thereof or any Use, even if Licensor has been advised of the possibility of such losses, costs, expenses, attorneys' or legal fees or costs, or damages of any kind anywhere. Where the exclusion or limitation of liability is limited by applicable law, this exclusion and limitation of liability applies to the greatest extent not limited by such applicable law.

5.3 The disclaimer of representations and warranties and the exclusion and limitation of liability under Sections 5.1 and 5.2 shall be interpreted in a manner that, to the extent possible, most closely approximates an absolute disclaimer and waiver of all liability.

6. Term and Termination.

6.1 This License and the license and rights hereunder are effective from the time when User accepts and agrees to this License until the expiration or termination of the Licensed Rights or the termination of this Licensed under Section 6.2, whichever occurs earlier (the "Term").

6.2 This License, and the license and rights hereunder, terminate automatically upon User’s breach or non-compliance with any of the terms, conditions, or provisions of this License, provided that, if User fully cures and corrects such breach or non-compliance within thirty (30) days after User’s first discovery of such breach or non-compliance, this License and the license and rights hereunder are reinstated automatically.

6.3 The provisions of Sections 1, 2.1(d) and 3.2 (with regard to any Separate Derivative created by User prior to the expiration or termination of this License), 4, 5, and 7, and this Section 6.3, shall survive any termination or expiration of this License.

7. Miscellaneous.

7.1 User recognizes that any actual or potential violation, breach, or non-performance of, or default under, any provision in this License may cause irreparable injury to Licensor for which Licensor may have no adequate remedy at law. User agrees that Licensor shall be entitled to seek injunctive relief or specific performance, without need or obligation to post any bond, to enforce any obligation, agreement, covenant, term and condition under this License, in addition to any other rights and remedies available to Licensor, all as Licensor elects in its sole discretion.

7.2 This License does not constitute, and shall not be construed as constituting, a partnership or joint venture between User, Licensor, or any other person. No third party shall be any beneficiary, intended or unintended, under this License.

7.3 User may not assign or transfer this License or any right hereunder or part hereof, or delegate any obligation under this License, without the express prior written consent of Licensor; any such unpermitted transfer, assignment, or delegation shall be null and void. Otherwise, this License shall bind any successor and permitted assign of User. Licensor may transfer or assign this Agreement or any right hereunder, or delegate any obligation hereunder, at any time in its sole discretion, including, without limitation, in connection with any assign, transfer, or conveyance of any Licensed Right

7.4 “Section” refers to any of the numbered sections of this License. Any reference to any law shall be construed as a reference to that law as amended or changed at the relevant time. Where a provision of this License states that a party “shall” or “will” perform or act or not act in some manner, such party is legally obligated to do so in accordance with such provision this License. Section headings and titles are intended solely for the convenience of the parties.

7.5 This License constitutes the entire understanding and agreement between User and Licensor related to the subject matter hereof. No right or remedy of User or Licensor under this License may be waived, discharged, or changed other than by a written instrument expressly identifying such right or remedy and signed by User or Licensor, as applicable. No amendment, modification, or change of this License or any term, condition, or provision of this License will be binding upon User and Licensor unless expressly set forth in a writing signed by each of User and Licensor through its authorized representative. A failure of User or Licensor to exercise any right or remedy under this License shall not be deemed to be a waiver of any right or remedy hereunder.

7.6 This License, any performance hereunder, the interpretation, construction, validity, and enforceability of this License and any term, condition, and provision of this License, and any dispute, and the resolution of any dispute, under this License shall be governed by the law of the State of New York, United States of America, without regard to any conflicts of laws provisions thereof that would result in the application of the law of any other jurisdiction.

7.7 If any term, condition, or provision of this License is held to be invalid or unenforceable, the meaning thereof will be construed, to the extent feasible, so as to render the provision enforceable, and if no feasible interpretation shall save such provision, it will be severed from the remainder of this License, as appropriate, which remainder shall remain in full force and effect unless the severed provision is essential and material to the rights or benefits received by User and Licensor, in which case this License shall be deemed terminated (subject to Section 6.3, as applicable).

Appendix B: Changelog

Version 3.0.0-20250217 (Draft Feb 17, 2025)

Summary of major changes since version 2.3:

1. Simplified versioning (ADR-41) included in § 5 Product Footprint Lifecycle.

2. Simplified filtering for Sync and Async API (ADR-42)

3. Add Biogenic Emissions and Removals (ADR-45)

4. Include attributes for CCU (ADR-46)

5. Consistent typing of real numbers (ADR-39)

6. Aditional units for service-related footprints (ADR-40)

7. Clarification of unit of measurement and product amount (ADR-36)

8. Common URN structure for product ids and classification id’s (ADR-34)

Data model changes:

Properties added:

• declaredUnitOfMeasurement

• declaredUnitAmount

• pcfExcludingBiogenicCO2Withdrawal

• pcfIncludingBiogenicCO2Withdrawal

• biogenicNonCO2Emissions

• biogenicCO2Withdrawal

• landUseChangeGhgEmissions

• landCarbonLeakage

• landManagementBiogenicCO2Emissions

• landManagementBiogenicCO2Removals

• uncertifiedLandManagementCO2Removals

• landAreaOccupation

• outboundLogisticsGhgEmissions

• ipccCharacterizationFactors

• ccuOrigin

• ccuCarbonContent

• ccuCreditCertification

• ccuCalculationApproach

• verification

Properties removed:

• ProductFootprint/productCategoryCpc

• ProductFootprint/statusComment

• CarbonFootprint/pCfIncludingBiogenic

• CarbonFootprint/pCfIncludingBiogenic

• CarbonFootprint/dLucGhgEmissions

• CarbonFootprint/packagingEmissionsIncluded

• CarbonFootprint/landManagementGhgEmissions

• CarbonFootprint/crossSectoralStandardsUsed

• CarbonFootprint/declaredUnit

• CarbonFootprint/biogenicCarbonWithdrawal

• CarbonFootprint/uncertaintyAssessmentDescription

• Assurance/assurance

• Assurance/level

• Assurance/boundary

• DataQualityIndicators/coveragePercent

• DataQualityIndicators/reliabilityDQR

• DataQualityIndicators/completenessDQR

Properties and types renamed:

• Assurance is now Verification

• CarbonFootprint/assurance renamed to verification

Version 3.0.0-20250212 (Feb 12, 2025)

Summary of changes:

1. Simplified versioning (ADR-41) included in § 5 Product Footprint Lifecycle.

2. Deprecation of ProductFootprint.version and ProductFootprint.updated properties.

3. Removed ProductFootprint.statusComment property.

4. Added paragraph on § 5.3 Validity Period to § 5 Product Footprint Lifecycle

Version 3.0.0-20250211 (Feb 11, 2025)

Summary of changes:

1. Addition of the following properties on biogenic emissions and withdrawals related to land-use (ADR-45):

   • pCfIncludingBiogenicBeforeCO2Withdrawal

   • landUseGhgEmissions

   • landUseCarbonLeakage

   • landManagementBiogenicCO2Removals

   • biogenicCO2Withdrawal

   • otherBiogenicGhgEmissions

   • biogenicNonCO2Emissions

   • landManagementGhgEmissions

   • landManagementUnspecifiedGhgEmissions

   • landAreaOccupation

2. Removal of the following properties

   • iLucGhgEmissions

   • dLucGhgEmissions

   • landManagementGhgEmissions

   • biogenicCarbonWithdrawal

   • otherBiogenicGhgEmissions

3. Properties for clarification of unit of measuremnt and declared unit amount (ADR-36):

   • declaredUnitOfMeasurement replaces declaredUnit

   • declaredUnitAmount replaces unitaryProductAmount

   • added productMassPerDeclaredUnit

Version 3.0.0-20250207 (Feb 7, 2025)

Summary of changes:

1. Removal of ProductFootprint/productCategoryCpc deprecated in 2.3 being superseded by ProductFootprint/productClassifications

2. Removal of CarbonFootprint/characterizationFactors deprecated in 2.2 replaced by CarbonFootprint/ipccCharacterizationFactors

3. Removal of CarbonFootprint/crossSectoralStandardsUsed deprecated in 2.3 replaced by CarbonFootprint/crossSectoralStandards

4. Property comment now optional (ADR31).

5. Property boundaryProcessesDescription> now optional (ADR31).

6. Property exemptedEmissionsDescription now optional (ADR31).

7. Assurance providername now optional

8. Remove CarbonFootprint/packagingEmissionsIncluded.

9. DQR ratings technologicalDQR, temporalDQR, geographicalDQR, completenessDQR, reliabilityDQR now range between 1 and 5.

Version 3.0.0-20250127 (Jan 27, 2025)

Summary of changes:

1. Removal of property assurance on Assurance object (ADR44)

Version 3.0.0-20241212 (Dec 12, 2024)

Summary of changes:

1. Updated references to the upcoming PACT Framework 3.0

2. Deprecation of property productCategoryCpc for 3.0 (ADR37)

3. Property comment advised optional 3.0 (ADR31)

4. Property boundaryProcessesDescription advised optional 3.0 (ADR31)

5. Property exemptedEmissionsDescription advised optional 3.0 ADR31)

6. Deprecation of property characterizationFactors for 3.0 (ADR28)

7. Removal of crossSectoralStandardsUsed which has been deprecated in 2.3 and is now superseeded by extensible crossSectoralStandards (ADR32).

8. Assurance/providername advised 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)

Release.

Version 2.3.0-20241010 (October 10, 2024)

1. Sunsetting the Pathfinder name replacing Pathfinder Framework with 'PACT Methodology' and 'Pathfinder Network' with 'PACT Network'. Exceptions are technical id’s for the Events (org.wbcsd.pathfinder.xxx) and mentions in the changelog.

2. Added chapter § 6 Product Identification and Classification including specification and examples for a common URN namespace syntax for productIds (ADR34)

3. Included URN namespace syntax for product classifications (ADR37)

4. Added optional property productClassifications (ADR37)

5. Advisement that property productCategoryCpc will be deprecated in version 3 (ADR37)

Version 2.3.0-20240904 (September 4, 2024)

1. Replaced the term 'reporting period' with 'reference period' for consistency with the attributes referencePeriodStart and referencePeriodEnd.

Version 2.3.0-20240625 (June 25, 2024)

1. Revision of productDescription to be more descriptive, following decision to keep attribute as mandatory

2. Indication of deprecation of crossSectoralStandardsUsed and introduction of crossSectoralStandards, reflecting consensus reached on ADR32

3. Addition of advisement that piece will be added as a DeclaredUnit in v3; addition of attribute productMassPerDeclaredUnit, per consensus reached on ADR33.

4. Clarification added to statusComment attribute, per consensus reached in Methodology WG, to include descriptive reasoning behind a given change in status.

5. Update contact email, Editor, and Former Editors

Version 2.2.1-20240624 (June 24, 2024)

Summary of changes:

1. add diagram with visual representation of asynchronous event processing workflow

Version 2.2.1-20240513 (May 13, 2024)

Summary of changes:

1. fixed § 8.9.1 Example Action ListFootprints request and response, § 8.9.3 Example PF Request and Response Events, § 8.9.4 Example Action GetFootprint request and response, and by removing spurious geographicScope object

Version 2.2.1-20240507 (May 7, 2024)

Summary of changes:

1. fixed dqi value types in all examples

2. clarification of DataQualityIndicators by removing misleading link to decimal

Version 2.2.1-20240430 (Apr 30, 2024)

Summary of changes:

1. Clarification of aircraftGhgEmissions definition to make it explicit that radiative forcing is excluded.

Version 2.2.0 (Apr 10, 2024)

Release.

Version 2.2.0-20240402 (Apr 02, 2024)

Summary of changes:

1. removal of notes referring to the transition from v1 to v2

2. fixed the incomplete assurance example and moved it to the appropriate section

3. addition of missing examples in the section

4. addition of advisement to exemptedEmissionsPercent stating that the upper boundary will be removed in version 3

5. clarification of how to handle error codes in ListResponseBody and GetResponseBody

Version 2.2.0-20240327 (Mar 27, 2024)

Summary of changes:

1. addition of the new § 4 Exchanging Footprints chapter

2. clarification of PF Request Event syntax, including the instruction that the ProductFootprintFragment should refer to one single productm

3. addition of a recommendation to include ProductIds in the PF Request Event request body

4. fixed the incorrect the value of pCfExcludingBiogenic in all relevant examples

5. addition of advisements to properties productCategoryCpc, comment, boundaryProcessesDescription, and exemptedEmissionsDescription stating that they will become OPTIONAL in version 3

Version 2.2.0-20240320 (Mar 20, 2024)

Summary of changes:

1. fixed example 28’s HTTP error code (from 401 to 400) in accordance with [rfc6749]

Version 2.2.0-20240312 (Mar 12, 2024)

Summary of changes:

1. deprecation of the characterizationFactors property

2. addition of a new ipccCharacterizationFactorsSources property

3. updates to Action Action Events implementation requirement - changed from OPTIONAL to MANDATORY

4. addition of an Example for a ProductFootprintFragment indicating a query for a PCF via productId

5. addition of Examples of a PCF request and response Action Event flow

Version 2.1.0 (Dec 07, 2023)

This version introduces additional mandatory functionality:

1. A new authentication flow (§ 8.3 Authentication Flow) is specified which allows discovery of the AuthEndpoint through an OpenId Provider Configuration Document. The flow is backwards-compatible with the 2.0.x-series of authentication flow based on the AuthSubpath/auth/token syntax.

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 clarification 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 § 8.5 Action ListFootprints the semantics of the Filter processing being OPTIONAL by introducing section § 8.5.1 Filtering

2. clarifies that a host system must return HTTP error status codes if it does not implement the events endpoint (see § 8.7 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 § 7.10 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 (§ 8.7 Action Events)

3. support for data model extensions (§ 7.7 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 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 for CAS, InChi and custom URN’s.

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 § 8.5.2 Pagination

• Action Events: section § 8.7 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 crosssectoralstandardset-json

3. Change to the minimum size of the set productOrSectorSpecificRules 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 § 8.4 Action Authenticate

6. Addition of an authentication flow specification in chapter § 8.3 Authentication Flow

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

8. Improved wording in section § 8.8 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 § 8.8 Error responses

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

9. Addition of Section § 8.9.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 § 7.6 CarbonFootprint and § 7.5 ProductFootprint

13. Removal of data types PositiveDecimal, SpecVersionString, VersionInteger