iLEAP Technical Specifications (Version 0.1.0)

1. Introduction

• Corporates have a growing need to calculate and report logistics emissions data with increased degrees of accuracy and transparency. With this purpose, they aim to shift from default and modeled data towards primary data that reflect their supply chain emissions with precision.

• This document specifies a § 6 Data Model and the data transactions necessary for the interoperable exchange of primary logistics emissions data, ensuring they are structured to facilitate the calculation of Product Carbon Footprints (PCFs)

• Grounded in the [GLEC] Framework and [ISO14083], this technical specification adopts the format established by the Pathfinder Framework and Pathfinder Technical Specifications. It conforms the foundational semantics framework for the SFC Data Exchange Network project.

• The adoption of this specification enables various stakeholders within the logistics value chain to exchange data, facilitating emissions calculations at the shipment, TCE, and TOC levels, and integration of these calculations at the PCF level.

1.1. Out of Scope

This specifcation does not cover the following topics or aspects as they are covered elsewhere or declared as out of scope of this specification:

1. Methodology for the calculation of logistics-related emissions which is specified in the [GLEC] Framework and [ISO14083].

2. Black Carbon (Accounting).

3. How to exactly capture necessary primary activity data for the calculation of HOCs or TOCs (i.e. through telematics systems, TMS, or others).

4. Pilot decentralized data exchange following data space governance principles, as covered in the SFC Data Exchange Network project.

5. How to establish contractual obligations between parties for the provision of data.

6. How to perform data audits and verification.

7. Market based approach for electricity emissions accounting.

8. Book and claim methods to track the environmental attributes of low emission transport solutions separately from the physical delivery. This will be incorporated in later versions of these technical specifications.

9. Variables for detailed GHG emissions modelling, as described in [ISO14083], Section 13.4.3 and Annex M. The current data model is considered a key enabler for primary data collection, where its main focus lays. The basic use of modelled and default data is supported, but detailed parameters for modelling are excluded from the current version.

10. Modes of transport cable car and pipelines. These will be incorporated in future versions of these technical specifications.

11. Refrigerant emissions, due to leakage of refrigerants used by vehicles and hubs, as described in [ISO14083], Annex I. This will be incorporated in later versions of these technical specifications.

The current technical specifications are undergoing continuous refinement as part of the ongoing iLEAP project. Significant modifications may be introduced as the project progresses. Certain subsections intentionally remain blank and will be filled in during subsequent stages of the iLEAP project.

2. Definitions

2.1. ISO14083- and GLEC-Framework-related Definitions

Transport Operation Category (TOC )

A Transport Operation Category is a grouping of transport services sharing similar characteristics. [GLEC] Framework.

Hub Operation Category (HOC )

A Hub Operation Category is a grouping of hub operations sharing similar characteristics. [GLEC] Framework.

Transport Chain (TC )

A Transport Chain as defined in the [GLEC] Framework. A TC consists of 1 or more Transport Chain Elements.

Transport Chain Element (TCE)

A Transport Chain Element is one element of the transport chain. It can consist of a transport activity or a hub activity. [GLEC] Framework.

Transport Operator

Refers to the party that carries out the transport service. See [ISO14083], Section 3.1.30.

Transport Service Organizer

Refers to the party providing transport services, where some of the operations are subcontrated to a third party, usually a Transport Operator. See [ISO14083], Section 3.1.32.

Transport Service User

Refers to the party that purchases and or utilizes a transport service. It could be a shipper or a Transport Service Organizer. See [ISO14083], Section 3.1.33.

Hub Activity

The operations carried out at a hub, measured in the hub’s throughput. [GLEC] Framework.

Shipment

A shipment refers to the goods in a commercial transaction between a seller and a buyer. It encompasses the consignments transported as part of this transaction via a transport chain from the consignor to the consignee. See [ISO14083], Section 3.1.20.

Consignment

A consignment refers to a quantifiable quantity of cargo that can be distinctly identified as a single unit. It is transported from a sender or consignor to a receiver or consignee, irrespective of the mode of transportation employed. See [ISO14083], Section 3.1.4.

Transport Activity

Transport activity for each consignment is calculated by multiplying the consignment’s mass by the TCE distance. It is measured with unit ton kilometer. See [ISO14083] Section 3.1.24 and the [GLEC] Framework.

Distance

See Transport Distance and Actual Distance

Transport Distance

Refers to the distance covered from the consignor to the consignee during the transportation of the freight. [GLEC] Framework. See also [ISO14083] 3.1.27.

Actual Distance

The actual route (with unit kilometer) taken for a consignment. [GLEC] Framework. See also [ISO14083] Section 3.1.27.1.

Shortest Feasible Distance (SFD)

It represents the shortest practical route between two places taking into account the real operating conditions. [GLEC] Framework.

Great Circle Distance (GCD)

It is the shortest distance between two points by crow-line, including the curving of the earth. It is an approach used in air transport. [GLEC] Framework.

Primary Data

Data based on direct measurements of energy consumption. Also see [GLEC] Framework.

Secondary Data

Any data that is not primary data. It applies to modelled and default data. [GLEC] Framework.

2.2. Auxillary Definitions

Data Transaction

see § 4 Data Transactions

Shipper

An entity which sends goods for transport; e.g. buying transport services from Transport Service Organizers or Transport Operators. See [GLEC] Framework.

Smart Freight Centre (SFC )

The Smart Freight Centre Organisation.

Hub Operator

A party that is offering hub services, including warehousing and transshipment center services.

Host System

See Pathfinder Tech Specs for the definition. Here, a host system additionally implements support for 1 or more data transactions (§ 4 Data Transactions).

Data Owner

See Pathfinder Tech Specs for the definition.

Data Recipient

See Pathfinder Tech Specs for the definition.

ShipmentFootprint

See § 6.1 ShipmentFootprint for the definition.

Shipment id

A digital identifier which uniquely identifies a Shipment.

Consignment id

A digital identifier which uniquely identifies a Consignment.

Tool Provider

Provider of software, tools, services, or programs that support companies in calculating and reporting logistics GHG emissions conforming to these technical specifications.

PCF

Product Carbon Footprint. See Pathfinder Tech Specs for further details

Access Token

See Pathfinder Tech Specs for the definition.

add a pathfinder tech specs normative reference to this document

3. Business Cases

Note: Non-normative section

This specification shall serve the general need of businesses for logistics GHG emissions accounting and reporting, conforming with the [GLEC] Framework and [ISO14083].

Given the nature of the logistics industry, and in order to reduce costs overall, logistics emissions transparency is made possible if all the parties involved are able to exchange emissions data in an interoperable manner.

To achieve this objective, the specification is guided by a set of business cases, which provide the framework for delineating subsequent data transactions (§ 4 Data Transactions).

The following business cases shall be supported by this specification:

Business Case #1: Quantify Avoided Emissions

A Transport Service User requests their service provider (Transport Service Organizer or (Transport Operator)) to share GHG emissions at the TCE level, to enable accurate emissions accounting based on primary data. This allows the Transport Service User to compare the logistics emissions reduction resulting of the introduction of specific operational changes with the emissions without the intervention. This is enabled through § 4.1 Data Transaction 1: TCE Data Exchange.

Business Case #2: Procurement of carbon-efficient services

A Transport Service Organizer requests their service provider (Transport Operator) to share GHG emissions at the TOC or HOC level. By incorporating emission intensities (HOCs or TOCs) in procurement processes, the Transport Service Organizer is enabled to choose services that offer carbon-efficiency advantages. This is enabled through § 4.2 Data Transaction 2: TOC Data Exchange.

Business Case #3: Enable Emissions Calculations from Activity Data

A Transport Service Organizer requests their service provider (Transport Operator) to share Transport Activity data to enable the estimation of emissions from the contracted services. This is enabled through § 4.3 Data Transaction 3: Transport Activity Data Exchange. ISSUE: I would argue this is not a business case, but just a data transaction.

Business Case #4: Disclose Logistics Emissions as Part of PCFs

A Transport Service User is requested by their customers to disclose logistics emissions as part of a PCF. This is enabled through the usage of the Pathfinder Technical Specification and disclosing through so-called Data Model Extensions based on the iLEAP Data Model (§ 6 Data Model) . See the Pathfinder [DATA-MODEL-EXTENSIONS] specification.

3.1. Potential additional Business Cases

Business Case #a1: Forecasting

A Transport Service User requests their service provider (Transport Service Organizer or Transport Operator) to share GHG emissions at the TOC or HOC level. This enables the Transport Service User to forecast emissions related to specific activities or services, before these take place.

Business Case #a2: Book & Claim

A Transport Service Organizer requests their service provider (Transport Operator) to share with them emissions attributes according to a book & claim scheme.

Note: This business case is currently out of scope. It might be supported in the future, as book & claim methodologies and related variables are considered in scope of these technical specifications.

4. Data Transactions

A data transaction is an abstraction for the exchange of data between two parties, serving one or more business cases (§ 3 Business Cases).

Its function is to facilitate interoperability between different parties by explaining the context and their intention(s).

Each transaction combines the iLEAP data model (§ 6 Data Model) with the Pathfinder Data Exchange Protocol (§ 7.2 Pathfinder Integration) to enable interoperability between host systems.

The following diagram shows how the three data transactions (defined below) are related:

Note: A Tool Provider can assume various roles on behalf of the Transport Service User, Transport Service Organizer or Transport Operator, as outlined in the data transactions below. They can serve as mediators in activities involving data collection, calculation, and reporting.

4.1. Data Transaction 1: TCE Data Exchange

This data transaction enables a Transport Service User (for example, a shipper) to receive Transport Chain Elements emissions related data (encoded as TCEs) from a Transport Operator or a Transport Service Organizer for a single shipment.

For this, the Transport Operator or the Transport Service Organizer MUST

1. first calculate 1 or more TCEs emissions related data in accordance with the [GLEC] Framework and [ISO14083], and then

2. make the resulting ShipmentFootprint available to the Transport Service User through the Pathfinder Network API (see § 7.2.1 ServiceFootprint).

The Transport Service User CAN then derive the Transport Chain (TC) using the shipment id, by

1. collecting the TCEs from all the Transport Operators and the Transport Service Organizers related to the shipment

2. forming the TC from the collected TCEs

3. calculating the logistics emissions of the shipment in accordance with the [GLEC] Framework and [ISO14083].

Note: For an example exchange, see § 5 End-to-End Example

4.2. Data Transaction 2: TOC Data Exchange

This data transaction enables a Transport Service Organizer to receive TOC emission intensity related data from a Transport Operator.

The provision of emission intensity data at the TOC level would enable the Transport Service Organizer to collect the necessary information to calculate emissions according to the GLEC Framework and [ISO14083]. It could also facilitate the inclusion of emission intensity in procurement processes, allowing for the provision of services that offer carbon-efficiency advantages (see Business Case 2).

For this, the Transport Operator or Transport Service Organizer MUST

1. first calculate 1 or more TOCs in accordance with the [GLEC] Framework and [ISO14083], and then

2. make the resulting TOCs available through the Pathfinder Network API (see § 7.2 Pathfinder Integration).

Note: The details on how to define and to calculate TOCs and HOCs are specified in [ISO14083] and guidance provided through the [GLEC] Framework. Details of the calculation method are out of scope of this specification.

4.3. Data Transaction 3: Transport Activity Data Exchange

This data transaction enables a Transport Service Organizer or a Transport Service User to receive Transport Activity Data from a Transport Operator.

For this, the Transport Operator MUST

1. first collect Transport Activity Data belonging to a consignment identified by the consignment id

2. calculate the TAD (see § 6.5 Transport Activity Data (TAD)) given the consignment id

3. make the resulting TAD available through the Pathfinder Network API.

The Transport Service Organizer or Transport Service User CAN then retrieve the TADs using the consignment ids.

Note: This data transaction is considered necessary by logistics parties. Especially for SMEs, lacking the capabilities to report curated emissions data, the option to provide activity data to their customers should be given.

5. End-to-End Example

Note: Non-normative section

This section provides an end-to-end example of how the data transactions (§ 4 Data Transactions) enable logistics emissions transparency for a single shipment.

The following hypothetical parties are involved:

Transport Service User S

A Transport Service User which wants to calculate the logistics emissions of a shipment from Rotterdam to Prague. The shipper has a contract with the Transport Service Organizer Z.

S operates a host system which implements Transaction 1 (§ 4.1 Data Transaction 1: TCE Data Exchange) to collect TCEs. Based on the collected TCEs, S can calculate Transport Chains (TCs) and thereby calculate and gain logistics emissions transparency.

Transport Service Organizer Z

A Transport Service Organizer responsible for a shipment from Rotterdam to Prague.

The Transport Service Organizer contracts Transport Operator A and Transport Operator B to perform the transport.

This operator has a host system which implements Transaction 1 (§ 4.1 Data Transaction 1: TCE Data Exchange) as well as Transaction 2 (§ 4.2 Data Transaction 2: TOC Data Exchange).

Through this, the operator is able to eventually calculate TCEs and TOCs, so that they can provide data to Transport Service User S.

Transport Operator A

A Transport Operator which is responsible for the first leg of the shipment.

This Operator has a host system which is capable of calculating TCEs and TOCs data.

Through this, the operator can make Transport Chain Element-level data available to the Transport Service Organizer Z, which Z can fetch using Transaction 1 (§ 4.1 Data Transaction 1: TCE Data Exchange).

Transport Operator B

Another Transport Operator which is responsible for the second leg of the shipment.

This Transport Operator is capable of making TAD data avialable to the Transport Service Organizer Z.

5.1. Data Transactions Executed

Note: In this hypothetical example, hub operations are currently ommitted.

Note: In this hypothetical example, when we refer to a party executing a transaction, we implicitly refer to their host systems which execute the tasks and transactions on their behalf.

5.1.1. Data Collection by Transport Service Organizer Z

As the transport consists of 2 legs, Z needs to collect data from the 2 Transport Operators A and B.

For this, the Transport Service Organizer Z performs the following data transactions:

1. Z executes § 4.1 Data Transaction 1: TCE Data Exchange with Transport Operator A to collect the TCEs for the first leg of the shipment.

2. As Transport Operator B does not support § 4.1 Data Transaction 1: TCE Data Exchange, Z performs § 4.3 Data Transaction 3: Transport Activity Data Exchange with Transport Operator B to collect the TAD for the second leg of the shipment.

3. Z then calculates the TCEs for the 2nd leg of the shipment based on the TAD data and modelled or default factors.

5.1.2. Data Collection by Transport Service User S

After Transport Service Organizer Z has performed its data collection, the Transport Service User S can calculate the logistics emissions of the shipment by

1. collecting the TCEs from Z using the shipment id and § 4.1 Data Transaction 1: TCE Data Exchange, storing the resulting TCEs in e.g. its database.

2. S can further verify the TCEs by collecting the TOCs from Z using § 4.2 Data Transaction 2: TOC Data Exchange

3. To compute the logistics emissions, Z can form the TC from the collected TCEs by taking the TCEs of step 1 and by calculating the logistics emissions for this shipment by following the [GLEC] Framework and [ISO14083].

5.2. Example HTTP Calls

5.2.1. Data Collection by Transport Service Organizer Z

To collect the TCEs from Transport Operator A, Z performs the following HTTP call.

Note: The call to /footprints can return several footprints, 1 for each shipment. By filtering, e.g. by the shipment id, Z can retrieve the TCEs for the shipment of interest (not shown below).

The highlighted lines show the data exchanged according to the ShipmentFootprint data model.

curl -X 'GET' \
'https://api.transport-operator-a.com/2/footprints'

{    "id": "d9be4477-e351-45b3-acd9-e1da05e6f633",    "specVersion": "2.0.0",    "version": 0,    "created": "2022-05-22T21:47:32Z",    "status": "Active",    "companyName": "Super Duper Transport Co.",    "companyIds": [ "urn:epc:id:sgln:4063973.00000.8" ],    "productDescription": "Logistics emissions related to shipment with ID 1237890",    "productIds": [ "urn:pathfinder:product:customcode:vendor-assigned:1237890" ],    "productCategoryCpc": "83117",    "productNameCompany": "Shipment with ID 1237890",    "comment": "",    "pcf": {      "declaredUnit": "ton kilometer",      "unitaryProductAmount": "36.801",      "pCfExcludingBiogenic": "3.6801",      "fossilGhgEmissions": "3.6801",      "fossilCarbonContent": "0.0",      "biogenicCarbonContent": "0.0",      "characterizationFactors": "AR5",      "crossSectoralStandardsUsed": [ "GHG Protocol Product standard" ],      "productOrSectorSpecificRules": [],      "boundaryProcessesDescription": "SFC GLEC Framework-conforming (W2W CO2e emissions)",      "referencePeriodStart": "2021-01-01T00:00:00Z",      "referencePeriodEnd": "2022-01-01T00:00:00Z",      "secondaryEmissionFactorSources": [ { "name": "GLEC", "version": "3.0" } ],      "exemptedEmissionsPercent": 0.0,      "exemptedEmissionsDescription": "",      "packagingEmissionsIncluded": true,      "primaryDataShare": 100.0    },    "extensions": [      {        "specVersion": "2.0.0",        "dataSchema": "https://catalog.carbon-transparency.com/sfc-ileap/0.0.1/shipmentfootprint.json",        "data": {          "mass": "87",          "shipmentId": "1237890",          "tces": [            {              "tceId": "abcdef",              "tocId": "truck-40t-euro5-de",              "shipmentId": "1237890",              "mass": "87",              "distance": {                "actual": "423"              },              "transportActivity": "36.801",              "co2eWTW": "3.6801",              "co2eTTW": "3.2801"            }          ]        }      }    ]  }

5.2.2. Data Collection by Transport Service User S

To collect the TCEs data related to the shipment from Transport Organizer Z, S performs the following HTTP call which yields 2 TCEs.

Note: The call to /footprints can return several footprints, 1 for each shipment. By filtering, e.g. by the shipment id, Z can retrieve the TCEs for the shipment of interest (not shown below).

The highlighted lines show 2 TCEs which Z has collected and calculated for S.

curl -X 'GET' \
'https://api.transport-organizer.com/2/footprints'

{    "id": "fb1faac2-7712-458a-a1db-bace3a44abb4",    "specVersion": "2.0.0",    "version": 0,    "created": "2022-05-22T21:47:32Z",    "status": "Active",    "companyName": "Transport Organizer Z",    "companyIds": [ "urn:epc:id:sgln:123456.00000.8" ],    "productDescription": "Logistics emissions related to shipment with ID 1237890",    "productIds": [ "urn:pathfinder:product:customcode:vendor-assigned:1237890" ],    "productCategoryCpc": "83117",    "productNameCompany": "Shipment with ID 1237890",    "comment": "",    "pcf": {      "declaredUnit": "ton kilometer",      "unitaryProductAmount": "64.728",      "pCfExcludingBiogenic": "8,42769",      "fossilGhgEmissions": "8,42769",      "fossilCarbonContent": "0.0",      "biogenicCarbonContent": "0.0",      "characterizationFactors": "AR5",      "crossSectoralStandardsUsed": [ "GHG Protocol Product standard" ],      "productOrSectorSpecificRules": [],      "boundaryProcessesDescription": "SFC GLEC Framework-conforming (W2W CO2e emissions)",      "referencePeriodStart": "2021-01-01T00:00:00Z",      "referencePeriodEnd": "2022-01-01T00:00:00Z",      "secondaryEmissionFactorSources": [ { "name": "GLEC", "version": "3.0" } ],      "exemptedEmissionsPercent": 0.0,      "exemptedEmissionsDescription": "",      "packagingEmissionsIncluded": true,      "primaryDataShare": 56.85    },    "extensions": [      {        "specVersion": "2.0.0",        "dataSchema": "https://catalog.carbon-transparency.com/sfc-ileap/0.0.1/shipmentfootprint.json",        "data": {          "mass": "87",          "shipmentId": "1237890",          "tces": [            {              "tceId": "abcdef",              "tocId": "truck-40t-euro5-de",              "shipmentId": "1237890",              "mass": "87",              "distance": {                "actual": "423"              },              "transportActivity": "36.801",              "co2eWTW": "3.6801",              "co2eTTW": "3.2801"            },            {              "tceId": "ghijkl",              "tocId": "operator-z-truck-89sdff",              "shipmentId": "1237890",              "mass": "87",              "distance": {                "actual": "321"              },              "transportActivity": "27.927",              "co2eWTW": "4.74759",              "co2eTTW": "4.272831"            }          ]        }      }    ]  }

6. Data Model

Add a brief Intro to the data model? Potentially with brief diagram or explanation on how shipment, TCE, TOC etc. relate to each other?

6.1. ShipmentFootprint

ShipmentFootprint is a data type that contains 1 or more Transport Chain Elements (encoded as TCEs) for a single shipment and from a single entity (a Transport Operator or a Transport Service Organizer).

By collecting 1 or more ShipmentFootprint for a shipment from Transport Operators and Transport Service Organizer, a Transport Service User can construct Transport Chains (TCs), and thereby calculate logistics emissions.

The way the above paragraphs are defined might lead to confusion.

To calculate a ShipmentFootprint, the Transport Operator or Transport Service Organizer MUST

• first calculate TCEs for a single shipment in accordance with § 6.2 Transport Chain Element ( TCE ),

• and then derives the ShipmentFootprint from the TCEs.

6.1.1. Data Attributes

A ShipmentFootprint has the following properties:

6.2. Transport Chain Element ( TCE )

The Data Type TCE models information related to a single Transport Chain Element.

TCEs are the building blocks to construct a Transport Chain (TC), enabling the calculation of logistics emissions.

Transport Chain Element Data can be obtained from direct measurement (see Primary Data or other measurements (see Secondary Data).

6.2.1. Data Attributes

The Data Type TCE has the following properties:

Note: The properties tocId and hocId are mutually exclusive, but one of them MUST be defined.

6.3. Transport Operation Category ( TOC )

The Data Type TOC contains transport operation category data.

The Transport Operator or Transport Service Organizer MUST calculate the TOC in accordance with the [GLEC] Framework.

The Transport Operator or Transport Service Organizer CAN then make the TOC available through the Pathfinder Network API as a ProductFootprint (see § 7.2.2 TOC).

Transport Operation Category data can be obtained from direct measurement (see primary data definition of [ISO14083]) or other measurements (see secondary data definition of [ISO14083]) such as modelled data or default value.

6.3.1. Data Attributes

The Data Type TOC has the following properties:

6.4. Hub Operation Category ( HOC )

The Data Type HOC contains HOC data. It is referenced in a Transport Chain Element through the hocId property.

Please, note that variables pertaining to the HOC Data Type have not been validated and are subject to undergo major updates.

HOCs are the building blocks for the calculation of a Transport Chain Element with hub operations.

6.4.1. Data Attributes

6.5. Transport Activity Data (TAD)

Transport Activity Data contains transport activity data-level data relating to transport or hub operations activities. This data type is meant for service providers (Transport Operator or Transport Service Organizer) lacking the capabilities to perform carbon emission calculations.

It captures fundamental attributes commonly accessible to service providers, and which are needed for the data recipient to make estimations or choose relevant defaults.

It can also be used by the service providers (Transport Operator or Transport Service Organizer) to provide additional transparency to their customers.

The data type is unimodal, and shold be used for capturing primary data.

6.5.1. Data Attributes

Note: The TAD data type is defined for the exchange of (primary) activity data for which no GHG emission or GHG emission intisities values have been calculated.

Properties of data type TAD:

this needs to be discussed with SFC and especially also Tool providers:

Note: At least one of the properties energyCarrier or feedstocks MUST be defined. If possible, both SHOULD be defined.

6.6. Additional Utility Data Types

6.6.1. Data Type GLECDistance

Data type GLECDistance represents a distance between origin and destination as defined in the [GLEC] Framework.

In JSON an GLECDistance MUST be encoded as a JSON Object.

At least one of the following properties of data type GLECDistance the MUST be defined:

6.6.2. Data Type Location

Properties of data type Location:

6.6.3. Data Type TransportMode

The Data Type TransportMode is an enumeration of the transport modes as defined in the [GLEC] Framework.

It MUST be encoded as a String using one of the following values:

Road

for transport mode road

Rail

for transport mode rail

Air

for transport mode air

Sea

for transport mode sea

InlandWaterway

for transport mode inland waterway

NOTE: : Hub operations are excluded from here, as these transport modes are defined for TOC, and HOC is defined separately

6.6.4. Data Type HubType

The Data Type HubType is an enumeration of the main hub types as defined in the [GLEC] Framework.

It MUST be encoded as a String using one of the following values:

Transshipment

refers to hubs where transshipment is the main service (>80% of goods handled)

StorageAndTransshipment

refers to hubs where both transshipment and warehousing are relevant services

Warehouse

refers to hubs where warehousing is the main service (>80% of goods handled)

LiquidBulkTerminal

refers to terminals equiped to handle cargo in liquid and gaseous forms

MaritimeContainerTerminal

refers to hubs where maritime containers are handled

6.6.5. Data Type Decimal

A decimal number.

In JSON, a Decimal MUST be encoded as a JSON String.

Note: the JSON String encoding is necessary to avoid floating point rounding errors.

"10"

"-0.123"

6.6.6. Data Type EnergyCarrier

Data type EnergyCarrier represents an energy carrier, including its feedstocks.

In JSON an EnergyCarrier MUST be encoded as a JSON Object.

The following properties are defined for data type EnergyCarrier:

6.6.7. Data Type EnergyCarrierType

Data type EnergyCarrierType represents the substance used to generate mechanical movement or heat and to generate chemical or physical processes as per the [GLEC] Framework.

It MUST be encoded as a String using one of the following values:

The enumeration of energy carrier types below will be evolved in future revisions. Account for this when implementing the validation of this property.

Diesel

refers to diesel

HVO

refers to Hydrotreated Vegetable Oil

Petrol

refers to petrol

CNG

refers to Compressed Natural Gas

LNG

refers to Liquefied Natural Gas

LPG

refers to Liquefied Petroleum Gas

HFO

refers to Heavy Fuel Oil

MGO

refers to Marine Gas Oil

Aviation fuel

refers to aviation fuel

Hydrogen

refers to hydrogen

Methanol

refers to methanol

Electric

refers to electricity

6.6.8. Data Type Feedstock

Data type Feedstock represents one feedstock of an EnergyCarrier.

In JSON an Feedstock MUST be encoded as a JSON Object.

The following properties are defined for data type Feedstock:

6.6.9. Data Type PackagingOrTrEqType

Data type PackagingOrTrEqType represents the category of relevant packaging or transport equipment units utilized for the transport of the consignment by the Transport Operator or Transport Service Organizer.

It MUST be encoded as a String using one of the following values:

The enumeration of packaging or transport equipment units below will be evolved in future revisions. Account for this when implementing the validation of this property.

Box

refers to boxes

Pallet

refers to pallets

Container

refers to containers

7. HTTP REST API

A host system MUST implement:

1. The endpoint for the exchange of Transport Activity Data (see § 7.1 Action TransportActivityData); and

2. The exchange of ShipmentFootprint and TOC as specified in § 7.2 Pathfinder Integration.

The exchange of logistics emissions data throught the § 6 Data Model presupposes the implementation of the HTTP REST API defined in [PACTDX] (Chapter 6).

Reusing the [PACTDX] data exchange protocol simplifies the integration of logistics emissions data into existing host systems software, especially if they are already used by Transport Service Users.

They can then use 1 interoperable API for the exchange of different categories of carbon emissions data related to GHG Protocol lifecycle stages (such as material acquisition and transport).

Additionally, by mapping the GLEC Data model into the [PACTDX] data model, existing host systems can be gradually extended to support calculation of logistics emissions in accordance with the [GLEC] Framework and [ISO14083].

7.1. Action TransportActivityData

Lists the data owner's Transport Activity Data with § 7.1.2 Pagination and optional § 7.1.1 Filtering

A Host system SHOULD implement an access management system to return only the transport activity data intended for the requesting data recipient.

7.1.1. Filtering

Filtering CAN be requested by a data recipient by supplying a filter statement through the Filter request parameter.

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

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

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

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

2. it CAN return an error response as defined in the Pathfinder Technical Specifications. For instance, a host system CAN return an error with code NotImplemented if it does not support a specific filter pair.

3. it CAN treat concatenated filters disjunctively, i.e., returning the union of the results of the individual filters.

7.1.2. Pagination

Host systems MUST implement pagination server-side such that

1. The host system MAY return less Transport Activity Data than requested through the Limit request parameter

2. The host system MUST return a Link header if there is additional Transport Activity Data 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 TransportActivityData 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 Transport Activity Data upon successful authentication (i.e. a Bearer token authentication as defined in [PACTDX] Section 6.3)

   2. MUST NOT return more data 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 is additional Transport Activity Data 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

7.1.3. Request Syntax

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

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 [PACTDX] section 6.3 Authentication Flow.

Filter

Filter is an OPTIONAL request parameter containing a filter statement. A filter statement is a list of name-value filter pairs. Each filter pair has a $name=$value syntax where $name is the (case-sensitive) name of the field to filter by, and $value the (case-insensitive) value to filter for. Filter pairs CAN be concatenated with &.

Get transport activity data with Feedstock "Fossil" and packagingOrTrEqType "Pallet"

GET /2/ileap/tad?feedstock=Fossil&packagingOrTrEqType=pallet HTTP/1.1

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.

7.1.4. Response Syntax

Response without a link header:

HTTP/1.1 TadStatusCode TadStatusText
content-type: application/json
content-length: ContentLength

TadResponseBody

Paginated response with a link header:

HTTP/1.1 TadStatusCode TadStatusText
content-type: application/json
content-length: ContentLength
link: PaginationLink; rel="next"

TadResponseBody

With response parameters

TadStatusCode

If the host system returns transport activity data, 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, as defined in the Pathfinder Technical Specifications.

TadStatusText

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

TadResponseBody

If the host system accepts the access token, the body MUST be a JSON object with property data with value the list of Transport Activity Data. The list MUST be encoded as a JSON array.

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.

ContentLength

The length of the Body. See [rfc9112].

PaginationLink

see pagination link and § 7.1.2 Pagination.

7.2. Pathfinder Integration

The Data types defined in § 6 Data Model are specific to [ISO14083] and the [GLEC] Framework.

This section specifies the integration of the data types ShipmentFootprint and TOC into the Pathfinder Data Model ([PACTDX] Chapter 4).

The integration of the data types ShipmentFootprint and TOC is achieved by storing them as extensions to the Pathfinder Data Model (see [DATA-MODEL-EXTENSIONS]). Therefore, all properties defined in the latter are also properties of the former. As a result, some properties relevant to logistics do not need to be defined in the § 6 Data Model. The list below contains the properties that were omitted for this reason.

7.2.1. ServiceFootprint

Note: This chapter refers to the PACT Data Model. See [PACTDX] Chapter 4 for further details.

A ServiceFootprint CAN be integrated into the Pathfinder Data Model ([PACTDX]) by storing a ShipmentFootprint as an extension (see [DATA-MODEL-EXTENSIONS]) in a ProductFootprint.

For interoperability reasons, additional attributes of such a ProductFootprint SHOULD be derived from the ShipmentFootprint. This is specified in the table below.

Note: Section ShipmentFootprint example contains an example.

7.2.2. TOC

Note: This chapter refers to the PACT Data Model. See [PACTDX] Chapter 4 for further details.

A TOC CAN be integrated into the Pathfinder Data Model ([PACTDX]) by storing a TOC as an extension (see [DATA-MODEL-EXTENSIONS]) in a ProductFootprint.

For interoperability reasons, several attributes of a ProductFootprint MUST be derived from the TOC. This is specified in the table below.

Note: Section TOC example contains an example.

Appendix A: Example PCFs with iLEAP Data embedded

In both examples, the value of dataSchema is currently placeholder and should not be taken as a link to the actual data schema. This will be updated as soon as possible.

ShipmentFootprint example

A Product Footprint with a ShipmentFootprint highlighted:

{    "id": "d9be4477-e351-45b3-acd9-e1da05e6f633",    "specVersion": "2.0.0",    "version": 0,    "created": "2022-05-22T21:47:32Z",    "status": "Active",    "companyName": "Super Duper Transport Co.",    "companyIds": [ "urn:epc:id:sgln:4063973.00000.8" ],    "productDescription": "Logistics emissions related to shipment with ID 1237890",    "productIds": [ "urn:pathfinder:product:customcode:vendor-assigned:1237890" ],    "productCategoryCpc": "83117",    "productNameCompany": "Shipment with ID 1237890",    "comment": "",    "pcf": {      "declaredUnit": "ton kilometer",      "unitaryProductAmount": "36.801",      "pCfExcludingBiogenic": "3.6801",      "fossilGhgEmissions": "3.6801",      "fossilCarbonContent": "0.0",      "biogenicCarbonContent": "0.0",      "characterizationFactors": "AR6",      "ipccCharacterizationFactorsSources": ["AR6"],      "crossSectoralStandardsUsed": [ "GHG Protocol Product standard" ],      "productOrSectorSpecificRules": [],      "boundaryProcessesDescription": "SFC GLEC Framework-conforming (W2W CO2e emissions)",      "referencePeriodStart": "2021-01-01T00:00:00Z",      "referencePeriodEnd": "2022-01-01T00:00:00Z",      "secondaryEmissionFactorSources": [ { "name": "GLEC", "version": "3.0" } ],      "exemptedEmissionsPercent": 0.0,      "exemptedEmissionsDescription": "",      "packagingEmissionsIncluded": true,      "primaryDataShare": 56.12    },    "extensions": [      {        "specVersion": "2.0.0",        "dataSchema": "https://api.ileap.sine.dev/openapi.json",        "data": {            "mass": "87",            "shipmentId": "1237890",            "tces": [              {                "tceId": "abcdef",                "tocId": "truck-40t-euro5-de",                "shipmentId": "1237890",                "mass": "87",                "distance": {                  "actual": "423"                },                "transportActivity": "36.801",                "co2eWTW": "3.6801",                "co2eTTW": "3.2801"            }          ]        }      }    ]  }

TOC example

A Product Footprint with a TOC highlighted:

{    "id": "f3c04ec8-b33a-43b1-9fa7-d6a448fd60af",    "specVersion": "2.0.0",    "version": 0,    "created": "2022-05-22T21:47:32Z",    "status": "Active",    "companyName": "Super Duper Transport Co.",    "companyIds": [ "urn:epc:id:sgln:4063973.00000.8" ],    "productDescription": "Logistics emissions related to TOC with ID 4561230",    "productIds": [ "urn:pathfinder:product:customcode:vendor-assigned:4561230" ],    "productCategoryCpc": "83117",    "productNameCompany": "TOC with ID 4561230",    "comment": "",    "pcf": {      "declaredUnit": "ton kilometer",      "unitaryProductAmount": "1",      "pCfExcludingBiogenic": "3.6801",      "fossilGhgEmissions": "3.6801",      "fossilCarbonContent": "0.0",      "biogenicCarbonContent": "0.0",      "characterizationFactors": "AR6",      "ipccCharacterizationFactorsSources": ["AR6"],      "crossSectoralStandardsUsed": [ "GHG Protocol Product standard" ],      "productOrSectorSpecificRules": [],      "boundaryProcessesDescription": "SFC GLEC Framework-conforming (W2W CO2e emissions)",      "referencePeriodStart": "2021-01-01T00:00:00Z",      "referencePeriodEnd": "2022-01-01T00:00:00Z",      "secondaryEmissionFactorSources": [ { "name": "GLEC", "version": "3.0" } ],      "exemptedEmissionsPercent": 0.0,      "exemptedEmissionsDescription": "",      "packagingEmissionsIncluded": false,      "primaryDataShare": 56.12    },    "extensions": [      {        "specVersion": "2.0.0",        "dataSchema": "https://api.ileap.sine.dev/openapi.json",        "data": {          "tocId": "4561230",          "isVerified": true,          "isAccredited": true,          "mode": "Road",          "temperatureControl": "refrigerated",          "truckLoadingSequence": "FTL",          "energyCarriers": [            "energyCarrier": "Diesel",            "co2eIntensityWTW": "3.6801",            "co2eIntensityTTW": "3.2801"          ],          "co2eIntensityWTW": "3.6801",          "co2eIntensityTTW": "3.2801",          "co2eIntensityThroughput": "tkm",        }      }    ]  }