Technical Specifications for PCF Data Exchange (Version 1.0.1)

1. Introduction

This document is the first specification in the context of the Pathfinder Network. It contains technical specifications to enable the exchange of standardized greenhouse gas (GHG) data at product level across interoperable technology solutions (i.e., the Use Case 001).

This Use Case 001 document specifies a data model and an HTTP REST API for the interoperable exchange of product footprint information with a special focus on product carbon footprints (PCF) between independent solutions. It further specifies rules for conformance of host systems, the digital representation of product footprints and related data data life cycle rules.

The semantic foundation of the data model is the Pathfinder Framework Version 1.

Developer resources can be found at the Use Case 001 repository.

Note: Version 2 of this specification can be accessed here.

1.1. Scope

The scope of this document and the feature coverage of the HTTP REST API is intentionally minimal by design. This document will be revised and additional use cases specified at a later stage, building on these specifications. The scope may be extended in future versions, for example to include services.

1.2. Intended Audience

This document is for

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

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

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

All parties are encouraged to review the technical specifications, inform the Partnership for Carbon Transparency (PACT), and SINE Foundation of any feedback (pact@wbcsd.org), and implement their own interoperable solutions.

1.3. About PACT and the Pathfinder Network

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

For further information, please refer to the PACT website www.carbon-transparency.com and the Pathfinder vision paper.

1.4. Disclaimer

This document is published as a version 1, acknowledging that additions or adjustments may be necessary (e.g., following an update of the Pathfinder Framework later this year). We will do our best to ensure updates do not create compatibility concerns, though we cannot exclude this possibility completely. 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.5. Changelog

1.5.1. Version 1.0.1

The following changes have been applied for version 1.0.1

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

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

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

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

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

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

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

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

   • addition of error response definition

   • improved specification of the error response JSON representation

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

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

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

9. Addition of Section § 6.6.2 Example Error Response

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

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

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

13. Removal of data types PositiveDecimal, SpecVersionString, VersionInteger

1.6. Acknowledgements

WBCSD would like to thank all PACT members, WBCSD staff, and others who shared their detailed and thoughtful input and contributed actively to the development of this document. WBCSD would also like to express special thanks to the companies participating in the pilot for testing the interoperable exchange of GHG emissions data across different solutions, as well as to those Solution Providers who have contributed to this document.

1.7. License

The license can be found in Appendix A: License.

2. Terminology

Data recipient

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

Data owner

The SCA sharing/being asked to share PCF data with another SCA.

interoperable

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

GHG (Greenhouse Gas (emissions))

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

Partnership for Carbon Transparency (PACT)

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

Pathfinder Framework

Guidance for the Accounting and Exchange of Product Life Cycle Emissions, building on existing standards and protocols, such as the GHG Protocol Product standard). See the Pathfinder Framework Version 1 for details.

Pathfinder Network

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

Product Carbon Footprint (PCF)

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

Supply Chain Actor (SCA)

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

Solution Provider

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

UN geographic region, UN geographic subregion

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

3. Conformance

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

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

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

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

4. Data Model

This section specifies a data model for product footprints conforming with the Pathfinder Framework guidelines. Additionally, this section specifies the data model representation in JavaScript Object Notation (JSON).

4.1. Data Type: ProductFootprint

This section needs to motivate the structure of a ProductFootprint and explain its nature as a data container for impact-related data

A ProductFootprint represents the carbon footprint of a product with values in accordance with the Pathfinder Framework.

4.1.1. Properties

A ProductFootprint has the following properties:

Subsequent revisions of this data model specification will update the value of specVersion according to the rules of Semantic Versioning 2.0.0.

4.2. Data Type: CarbonFootprint

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

4.2.1. Scope of a CarbonFootprint

Each CarbonFootprint is scoped by

1. Time: the time is defined by property reportingPeriodStart (including) and property reportingPeriodEnd (excluding); see the Pathfinder Framework Section 7.2.1

2. Geography: further set by the properties geographyRegionOrSubregion, geographyCountry, and geographyCountrySubdivision; see the Pathfinder Framework Section 7.2.2.

If a CarbonFootprint

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

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

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

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

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

4.2.2. Properties

The properties of a CarbonFootprint:

Note: The property biogenicEmissions will be revised once the GHG Protocol FLAG Standard is published.

Property unitaryProductAmount needs better specification text

4.3. Data Type: RegionOrSubregion

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

Africa

for the UN geographic region Africa

Americas

for the UN geographic region Americas

Asia

for the UN geographic region Asia

Europe

for the UN geographic region Europe

Oceania

for the UN geographic region Oceania

Australia and New Zealand

for the UN geographic subregion Australia and New Zealand

Central Asia

for the UN geographic subregion Central Asia

Eastern Asia

for the UN geographic subregion Eastern Asia

Eastern Europe

for the UN geographic subregion Eastern Europe

Latin America and the Caribbean

for the UN geographic subregion Latin America and the Caribbean

Melanesia

for the UN geographic subregion Melanesia

Micronesia

for the UN geographic subregion Micronesia

Northern Africa

for the UN geographic subregion Northern Africa

Northern America

for the UN geographic subregion Northern America

Northern Europe

for the UN geographic subregion Northern Europe

Polynesia

for the UN geographic subregion Polynesia

South-eastern Asia

for the UN geographic subregion South-eastern Asia

Southern Asia

for the UN geographic subregion Southern Asia

Southern Europe

for the UN geographic subregion Southern Europe

Sub-Saharan Africa

for the UN geographic subregion Sub-Saharan Africa

Western Asia

for the UN geographic subregion Western Asia

Western Europe

for the UN geographic subregion Western Europe

4.4. Data Type: EmissionFactorDSSet

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

4.4.1. JSON Data Representation

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

4.5. Data Type: EmissionFactorDS

An EmissionFactorDS references emission factor databases accepted under Version 1 of the Pathfinder Framework Section 6.2.

Note: Version 2 of the Pathfinder Framework will extend the coverage of emission factors data sources. This specification will reflect upcoming changes in future versions.

4.5.1. Properties

name (mandatory, data type: NonEmptyString)

Each EmissionFactorDS MUST include the property name with value the name of the emission factor database.

version (mandatory, data type: NonEmptyString)

Each EmissionFactorDS MUST include the property version with value the version of the emission factor database used.

4.5.2. JSON Representation

Each EmissionFactorDS MUST be encoded as a JSON object.

4.6. Data Type: BiogenicEmissions

BiogenicEmissions contains biogenic emission values according to the GHG Protocol FLAG Standard.

4.6.1. Properties

Data type BiogenicEmissions has the following properties.

At least one property of a BiogenicEmissions MUST be present.

4.7. Data Type: CrossSectoralStandard

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

GHG Protocol Product standard

for the GHG Protocol Product standard

ISO Standard 14067

for ISO Standard 14067

ISO Standard 14044

for ISO Standard 14044

4.7.1. JSON Reprsentation

Each CrossSectoralStandard MUST be encoded as a JSON string.

4.8. Data Type: CrossSectoralStandardSet

A set of CrossSectoralStandard values.

4.8.1. JSON Representation

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

4.9. Data Type: ProductOrSectorSpecificRule

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

4.9.1. Properties

operator (mandatory, data type: ProductOrSectorSpecificRuleOperator)

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

ruleNames (mandatory, data type: NonEmptyStringVector)

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

otherOperatorName (optional, data type: NonEmptyString)

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

4.9.2. JSON Representation

Each ProductOrSectorSpecificRule MUST be encoded as a JSON object.

4.10. Data Type: ProductOrSectorSpecificRuleSet

A set of ProductOrSectorSpecificRule of size 1 or larger.

4.10.1. JSON Representation

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

4.11. Data Type: ProductOrSectorSpecificRuleOperator

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

PEF

for EU / PEF Methodology PCRs

EPD International

for PCRs authored or published by EPD International

Other

for a PCR not published by the operators mentioned above

4.11.1. JSON Reprsentation

Each value is encoded as a JSON String.

4.12. Data Type: NonEmptyStringVector

A list of NonEmptyString of length 1 or greater.

4.12.1. JSON Representation

Each NonEmptyStringVector MUST be encoded as an array of NonEmptyStrings.

4.13. Data Type: CpcCode

A CpCode represents a UN CPC Code version 2.1 value.

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

4.13.1. JSON Representation

Each CpcCode MUST be encoded as a JSON String.

4.14. Data Type: DeclaredUnit

DeclaredUnit is the enumeration of accepted declared units with values

liter

for unit liter

kilogram

for unit kilogram

cubic meter

for cubic meter

kilowatt hour

for kilowatt hour

megajoule

for megajoule

ton kilometer

for ton kilometer

square meter

for square meter

4.14.1. JSON Reprsentation

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

4.15. Data Type: NonEmptyString

A String with 1 or more characters.

4.15.1. JSON Representation

Each NonEmptyString MUST be encoded as a JSON String.

4.16. Data Type: CompanyIdSet

A set of URNs of length 1 or greater.

4.16.1. JSON Representation

Each CompanyIdSet MUST be encoded as an array of strings.

4.17. Data Type: ProductIdSet

A set of ProductIds of size 1 or larger.

4.17.1. JSON Representation

Each ProductIdSet MUST be encoded as an array of strings.

4.18. Data Type: ProductId

Each ProductId MUST be a conforming URN with as namespace a value included in the Official IANA Registry of URN Namespaces.

4.19. Data Type: URN

A String conforming to the URN syntax.

4.19.1. JSON Representation

Each URN MUST be encoded as a JSON String.

4.20. Data Type: String

A regular UTF-8 String.

4.20.1. JSON Data Representation

Each String MUST be encoded as a JSON String.

4.21. Data Type: Percent

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

Example values:

4.21.1. JSON Representation

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

4.22. Data Type: StrictlyPositiveDecimal

A positive, non-zero Decimal.

Example values:

4.22.1. JSON Representation

See [§ 4.25.1 JSON Representation].

4.23. Data Type: DateTime

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

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

4.23.1. JSON Representation

Each DateTime MUST be encoded as a JSON String.

4.24. Data Type: ISO3166CC

An ISO 3166-2 alpha-2 country code.

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

4.24.1. JSON Representation

Each ISO3166CC MUST be encoded as a JSON String.

4.25. Data Type: Decimal

A dotted-decimal number.

Example values:

4.25.1. JSON Representation

Each Decimal MUST be encoded as a JSON String.

4.26. Data Type: PfId

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

4.26.1. JSON Representation

Each PfId MUST be encoded as a JSON String.

Example JSON string value:

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

5. Product Footprint Lifecycle

5.1. Introduction

A Product Footprint can be updated, for instance to incorporate a change in upstream carbon emission factors or to correct errors.

The purpose of this section is to clarify what constitutes an occasion for an update (§ 5.2 Definition of update) and to specify which kinds of changes (§ 5.3 Data life cycle rules) to a Product Footprint must be applied in such a case.

5.2. Definition of update

A Product Footprint update SHOULD be limited to correct reported values. A Product Footprint update SHOULD be done whenever the value of 1 or more properties of the Product Footprint change which could directly or indirectly affect the Product Footprint calculation or interpretation by data recipients of the Product Footprint.

A Product Footprint update MUST NOT occur to change the reporting period. For this case, a data owner MUST create a Product Footprint with a new Product Footprint identifier.

A Product Footprint update MUST NOT change the Product Footprint identifier.

5.3. Data life cycle rules

A Product Footprint CAN be updated by a data owner.

A Product Footprint update MUST include 1 or more changes to a property, excluding changes to properties version and updated. A change to a property includes a transition to or from being undefined.

Whenever a data owner or a host system updates a Product Footprint according to § 5.2 Definition of update,

1. it MUST set the value of property version to be by strictly greater than the value of the property version of all preceding footprints, and

2. it SHOULD set the value of property updated to the timestamp of the update. The value SHOULD be strictly greater than the value of the property updated of all preceding Product Footprints.

5.4. JSON Schema

add JSON Schema for ProductFootprint.

6. Use Case 001 HTTP REST API Version 1.0.0

6.1. Introduction

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

This version 1.0.1 release is the first publication towards this goal. Intentionally, the scope of the specifications is minimal in order to collect market feedback and to incorporate this in future revisions.

reword this introduction

6.2. Host System

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

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 Use Case 001 HTTP REST API, and

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

6.2.1. Out of scope

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

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

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

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

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

6.2.2. Establishing data exchange flows between Host Systems

add section on data exchange between host systems, detailing the information needed for establishing host system-to-host system data exchange, URL examples

6.2.3. A note on data synchronization between Host Systems

The data flow specified in this document is directed.

If a data owner has updated a product footprint, it is assumed that the product footprint is made available through the Use Case 001 HTTP REST API as soon as possible.
Additionally, each product footprint returned from a host system has properties to disclose whether a product footprint was updated. These properties are: created, updated, version. By comparing the value of these properties for a product footprint, identified by its id, solutions can determine whether a footprint has been updated.

Note: in future versions, the functionality for data exchange between host systems and capabilities to synchronize data will be specified and developed further.

add link to product lifecycle section

reword this section

6.3. Authentication and Request Flows

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

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

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

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

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

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

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

6.4. Actions reference

A host system MUST implement each of the following actions. A host system MUST only accept requests using https, not http. The host system MUST not respond to requests made using other protocols (not even with a 400 Error or any other http status codes).

A host system MAY offer the endpoints under a relative subpath. A host system MUST offer the Action ListFootprints and Action GetFootprint under the same Hostname and Subpath.

6.4.1. Action Authenticate

Request an access token using client credentials.

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

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

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

6.4.1.1. Request Syntax (HTTP/1.1)

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

AuthBody

With Request parameters:

AuthSubpath:

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

AuthHostname

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

BasicAuth

See [rfc6749] Section 4.4.2

AuthBody

See [rfc6749] Section 4.4

ContentLength

The length of the Body. See [rfc9112].

6.4.1.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 RFC 6749 Section 4.4. See § 6.3 Authentication and Request Flows for further details

6.4.2. Action ListFootprints

Lists product footprints with optional filtering by properties created or updated.

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

6.4.2.1. Request Syntax (HTTP/1.1)

GET Subpath/0/footprints?Filter HTTP/1.1
host: Hostname
authorization: Bearer BearerToken

with request parameters:

Subpath

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

Hostname

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

BearerToken

see Bearer Token of section § 6.3 Authentication and Request Flows

Filter

filter is an optional request parameter. If defined,

• the name of the HTTP request parameter MUST be filter

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

Additionally, the $filter statement MUST reference property created or property updated only and MUST use the eq operator only.

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

Additionally,

• if the request parameter Filter is defined against property updated, then only ProductFootprints with property updated defined and with a value equal to or greater than the timestamp given by the filter SHOULD be included in the Body; or

• if the filter is against property created, then only ProductFootprints with a creation time equal to or greater than the timestamp given by the filter SHOULD be included in the Body.

  Example value of Filter:

  $filter=updated ge 2020-03-01T00:00:00Z

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

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

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

6.4.3. Action GetFootprint

Retrieves product footprints.

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

6.4.3.1. Request Syntax

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

with request-specific parameters:

GetPfId

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

6.4.3.2. Response Syntax

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

GetResponseBody

With response parameters:

GetStatusCode

The HTTP Status Code of the response.

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

GetStatusText

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

GetResponseBody

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

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

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

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

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

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

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

6.5. Error responses

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.

A host system SHOULD conform to [rfc6750] Section 3 when returning a TokenExpired error response.

6.5.1. Error processing by a data recipient

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

6.6. Examples

6.6.1. Example Action ListFootprints request and response

GET /0/footprints 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": "d9be4477-e351-45b3-acd9-e1da05e6f633",
      "specVersion": "1.0.0",
      "version": 0,
      "created": "2022-05-22T21:47:32Z",
      "companyName": "My Corp",
      "companyIds": [
        "urn:uuid:51131FB5-42A2-4267-A402-0ECFEFAD1619",
        "urn:epc:id:sgln:4063973.00000.8"
      ],
      "productDescription": "Cote'd Or Ethanol",
      "productIds": [
        "urn:gtin:4712345060507"
      ],
      "productCategoryCpc": "3342",
      "productNameCompany": "Green Ethanol",
      "comment": "",
      "pcf": {
        "declaredUnit": "liter",
        "unitaryProductAmount": "12.0",
        "fossilGhgEmissions": "0.123",
        "biogenicEmissions": {
          "landUseEmissions": "0.001",
          "otherEmissions": "0"
        },
        "biogenicCarbonContent": "0.0",
        "reportingPeriodStart": "2021-01-01T00:00:00Z",
        "reportingPeriodEnd": "2022-01-01T00:00:00Z",
        "geography_country": "FR",
        "primaryDataShare": 56.12,
        "emissionFactorSources": [
          {
            "name": "Ecoinvent",
            "version": "1.2.3"
          }
        ],
        "boundaryProcessesDescription": "End-of-life included",
        "crossSectoralStandardsUsed": [
          "GHG Protocol Product standard"
        ],
        "productOrSectorSpecificRules": [
          {
            "operator": "EPD International",
            "ruleNames": [
              "ABC 2021"
            ]
          }
        ]
      }
    }
  ]
}

6.6.2. Example Error Response

GET /0/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"
}

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