index.bs

<pre class='metadata'>
Title: iLEAP Technical Specifications (Version 0.2.1-20250311)
Shortname: ileap-extension
Status: LD
Status Text: Draft Technical Specification
ED: https://sine-fdn.github.io/ileap-extension/
TR: https://sine-fdn.github.io/ileap-extension/TR/2024/ileap-extension-20240605/
Canonical URL: ED
Editor: Violetta Matzoros, https://www.smartfreightcentre.org, violetta.matzoros@smartfreightcentre.org
Editor: Gabriela Rubio Domingo, https://www.smartfreightcentre.org, gabriela.rubiodomingo@smartfreightcentre.org
Editor: Martin Pompéry, https://sine.foundation, martin@sine.foundation
Editor: Raimundo Henriques, https://sine.foundation, raimundo@sine.foundation
Repository: sine-fdn/ileap-extension
Abstract: This document outlines the semantics for logistics emissions data exchange as part of the [iLEAP Project](https://www.smartfreightcentre.org/en/our-programs/emissions-accounting/global-logistics-emissions-council/digitalization-program/ileap-integrating-logistics-emissions-and-pcfs/). Its format is based on the PACT Technical Specifications and supports the integration of Logistics Emissions Data Exchange into the PACT Network. Implementing this specification enables stakeholders within the supply chain to exchange data on logistics emissions. This facilitates the tracking of logistics emissions and the computation of their contribution to product carbon footprints.
Markup Shorthands: markdown yes
Boilerplate: omit conformance, omit copyright
Previous Version: https://sine-fdn.github.io/ileap-extension/TR/2024/ileap-extension-20240521/
Local Boilerplate: header yes
</pre>

# Introduction # {#introduction}

- Companies have a growing need to calculate and report logistics emissions with greater accuracy and transparency. They want to move from default and modeled data to primary data that accurately reflects their supply chain emissions.
- This document specifies a [[#data-model]] and the [=data transactions=] necessary for the interoperable exchange of primary logistics emissions data, ensuring that they are structured to facilitate the calculation of Product Carbon Footprints (PCFs).
- Based on the [[!GLEC]] Framework and [[!ISO14083]], this technical specification is built on top of the PACT Technical Specifications. In addition, it is based on the basic semantics and framework developed by the [SFC Data Exchange Network project](https://www.smartfreightcentre.org/en/our-programs/emissions-accounting/global-logistics-emissions-council/digitalization-program/sfc-exchange-network) and advances them further.
- Adopting this specification will enable the exchange of data between all actors in the logistics value chain, facilitating the calculation of emissions at the [=shipment=], [=Transport Chain Element|TCE=] and [=TOC=] levels, and the integration of these calculations at the [=PCF=] level.

Advisement: The iLEAP Technical Specifications will be continuously refined as part of the ongoing iLEAP project. Significant changes may be introduced as the project progresses.


## Out of Scope ## {#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, 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](https://www.smartfreightcentre.org/en/our-programs/emissions-accounting/global-logistics-emissions-council/digitalization-program/sfc-exchange-network).
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 for environmental attribute tracking separate from physical delivery. These will be incorporated in future 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 focuses on enabling primary data collection. Basic use of modeled and default data is supported, but detailed parameters remain excluded.
10. Modes of transport cable car and pipelines. These may be incorporated in future versions of these technical specifications.
11. Refrigerant emissions, as described in [[!ISO14083]], Annex I. These will be incorporated in future versions of these technical specifications.

## Document Statuses ## {#document-statuses}

The iLEAP Technical Specifications adhere to the [SemVer](https://semver.org/) standard and are
published according to a flow that clearly distinguishes work-in-progress from pre-releases and
stable releases. These are indicated by the status tag below at the top of the document. Possible
status tags are:

: Living Document

:: Work-in-progress. The version number is typically extended with the date on which the most recent
    changes were made (e.g., 0.2.1-20240523). Accessible at
    [https://sine-fdn.github.io/ileap-extension/](https://sine-fdn.github.io/ileap-extension/).

: Consultation Draft

:: Pre-release. Distributed for the purpose of obtaining community feedback. No further significant
    changes will be made until the release. Minor corrections may still be possible. Every
    Consultation Draft is assigned a stable, permanent, URL, e.g.,
    [https://sine-fdn.github.io/ileap-extension/TR/2024/ileap-extension-20240521/](https://sine-fdn.github.io/ileap-extension/TR/2024/ileap-extension-20240521/).

: Release

:: Stable release. No further changes will be made to this version. Any additional changes will be
    included in subsequent versions. Every Release is assigned a stable, permanent, URL, e.g.,
    [https://sine-fdn.github.io/ileap-extension/TR/2024/ileap-extension-20240605/](https://sine-fdn.github.io/ileap-extension/TR/2024/ileap-extension-20240605/).


# Definitions # {#definitions}

## ISO14083- and GLEC-Framework-related Definitions ## {#iso14083-definitions}
: <dfn>Actual Distance</dfn>
:: The actual route (with unit `kilometer`) taken for a consignment. [[!GLEC]] Framework. See also [[!ISO14083]] Section 3.1.27.1.

: <dfn>Consignment</dfn>
::
    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.

: <dfn>Distance</dfn>
:: See [=Transport Distance=] and [=Actual Distance=]

: <dfn>Great Circle Distance</dfn> (GCD)
::
    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.

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

: Hub Operation Category (<dfn>HOC</dfn>)
:: Represents a grouping of hub operations sharing similar characteristics.  [[!GLEC]] Framework.

: <dfn>Primary Data</dfn>
::
    Data based on direct measurements of energy consumption. Also see [[!GLEC]] Framework.

: <dfn>Secondary Data</dfn>
::
    Any data that is not primary data. It applies to modelled and default data. [[!GLEC]] Framework.

: <dfn>Shipment</dfn>
::
    A shipment refers to the goods in a commercial transaction between a seller and a buyer.
    Refers to the consignments transported as part of this transaction via a transport
    chain from the consignor to the consignee. See [[!ISO14083]], Section 3.1.20.

: <dfn>Shortest Feasible Distance</dfn> (SFD)
::
    Represents the shortest practical route between two places taking into account the real operating conditions. [[!GLEC]] Framework.

: <dfn>Transport Activity</dfn>
::
    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.

: Transport Chain (<dfn>TC</dfn> )
:: A Transport Chain as defined in the [[!GLEC]] Framework. A TC consists of 1 or more [=Transport Chain Elements=]. A TC corresponds to a shipment.

: <dfn>Transport Chain Element</dfn> (TCE)
:: Represents one element of the transport chain. It can consist of a transport activity or a hub activity. [[!GLEC]] Framework.

: <dfn>Transport Distance</dfn>
:: 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.

: Transport Operation Category (<dfn id='toc-dfn'>TOC</dfn>)
:: Represents a grouping of transport services sharing similar characteristics.  [[!GLEC]] Framework.

: <dfn>Transport Operator</dfn>
:: Refers to the party that carries out the transport service. See [[!ISO14083]], Section 3.1.30.

: <dfn>Transport Service Organizer</dfn>
:: 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.

: <dfn>Transport Service User</dfn>
:: 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.

## Auxillary Definitions ## {#auxillary-definitions}

: <dfn>Access Token</dfn>
:: See [PACT Tech Specs](https://wbcsd.github.io/tr/2023/data-exchange-protocol-20231207/#access-token) for the definition.

: <dfn>Consignment id</dfn>
::
    A digital identifier which uniquely identifies a [=Consignment=] relative to the [=Host system=] and to the [=Data recipient=].

: <dfn>Data Owner</dfn>
:: See [PACT Tech Specs](https://wbcsd.github.io/tr/2023/data-exchange-protocol-20231207/#data-owner) for the definition.

: <dfn>Data Recipient</dfn>
:: See [PACT Tech Specs](https://wbcsd.github.io/tr/2023/data-exchange-protocol-20231207/#data-recipient) for the definition.

: Data Transaction
:: See [[#txns]].

: <dfn>Host System</dfn>
:: See [PACT Tech Specs](https://wbcsd.github.io/tr/2023/data-exchange-protocol-20231207/#host-system) for the definition.
    Here, a host system additionally implements support for 1 or more data transactions ([[#txns]]).

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

: <dfn>PCF</dfn>
::
    Product Carbon Footprint. See [PACT Tech Specs](https://wbcsd.github.io/tr/data-exchange-protocol/#dt-carbonfootprint) for further details.

: ShipmentFootprint
:: See [[#dt-sf]] for the definition.

: <dfn>Shipment id</dfn>
::
    A digital identifier which uniquely identifies a [=Shipment=] relative to the [=Host system=] and to the [=Data recipient=].

: <dfn>Shipper</dfn>
:: 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 (<dfn>SFC</dfn> )
:: The [Smart Freight Centre](https://www.smartfreightcentre.org) Organization.

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


# Business Cases # {#business-cases}

Note: Non-normative section

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

Given the nature of the logistics industry, and in order to reduce costs overall, this specification aims at
enabling interoperability in the exchange of emissions data between different parties in the logistics value chain.

To achieve this objective, the specification is guided by a set of business cases which provide the
framework for delineating subsequent [[#txns|data transactions]] and the [[#data-model|iLEAP data model]].


## Quantification of (Avoided) Emissions ## {#business-case-1}

A [=Transport Service User=] requests its [=Transport Service Organizers=] or [=Transport Operators=] to provide it with the GHG emissions of [=Shipments=].
The transport service user is interested in accessing accurate emission and emission intensity values based on actual measurements ("primary data").

Accurate logistics emissions values also enable the Transport Service User to compare logistics emissions and the resulting reductions from operational measures.

Data Transactions #1 ([[#txn1]]) and #2 ([[#txn2]]) enable this business case.


## Procurement of Carbon-Efficient Logistics Services ## {#business-case-2}

A [=Transport Service Organizer=] requests their [=Transport Operators=] to share GHG emission intensity information at the [=TOC=] or [=HOC=] level.
Similarly, a [=Transport Service User=] requests intensity information from its [=Transport Service Organizers=] and [=Transport Operators=].

By incorporating emission intensities in procurement processes, the parties are enabled to select services by carbon-efficiency advantages.

Data Transaction #2 [[#txn2]] enable this business case.


## Simplified Emissions Calculation from Transport Activity Data ## {#business-case-3}

Consider the scenario where a [=Transport Operator=], and possibly also [=Transport Service Organizer=], is not yet able to calculate GHG emissions according to the [[!GLEC|GLEC Framework]] and [[!ISO14083]].

In such a case, the party may choose to collect [=Transport Activity Data=], that is, information related to a single shipment including mass, distance, and energy carriers used.

After collecting Transport Activity Data, the party can then contract a third party, such as a [=Tool Provider=], to calculate TOC and HOC level data from its Transport Activity Data.

This business case is particularly relevant for SMEs to reduce the entry barrier for logistics emissions reporting.

iLEAP generally simplifies data collection efforts for the parties involved in this business case.
For instance, each party needs to collect the activity data only once. This data can be then made available to multiple parties for different purposes, including business cases beyond emissions calculations.

Data Transaction #3 ([[#txn3]]) enables this business case.


## Additional Business Cases ## {#txns-appendix}


: Disclosure of Logistics Emissions as part of PCFs
::
    A [=Transport Service User=] is requested to disclose logistics emissions as part of a [=PCF=].
    A Transport Service User can disclose this data as a data model extension (see [[#pcf-mapping-sf]]).

    This is enabled through the usage of the PACT Technical Specifications
    and disclosing through so-called Data Model Extensions based on the iLEAP
    Data Model ([[#data-model]]) . See the PACT [[!DATA-MODEL-EXTENSIONS]] specification.


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

: Integration of Book & Claim
::
    Note: This business case is currently out of scope. It may be supported in the future, when book & claim attributes are included in these technical specifications.

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



# Data Transactions # {#txns}

A <dfn>data transaction</dfn> is an abstraction for the exchange of data between two parties, serving one or more business cases ([[#business-cases]]).

It facilitates interoperability between different parties by explaining the context and their intention(s).

Each transaction combines the iLEAP data model ([[#data-model]]) with the PACT
Data Exchange Protocol ([[#pcf-mapping]]), enabling interoperability between [=host systems=].

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

<figure id="figure-data-transactions">
  <img src="diagrams/transactions.png" width="30%" >
  <figcaption>Transactions diagram</figcaption>
</figure>

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.

## Data Transaction 1: TCE Data Exchange ## {#txn1}

This data transaction enables a [=Transport Service User=] (for example, a [=shipper=]) to receive [=Transport Chain Elements=]' emissions related data (encoded as <{TCE|TCEs}>) from a
[=Transport Operator=] or a [=Transport Service Organizer=] for a single [=shipment=].

To execute this transaction, the [=Transport Operator=] or the [=Transport Service Organizer=] MUST

1. calculate 1 or more TCEs' emissions data in accordance with the [[!GLEC]] Framework and [[!ISO14083]], and then
2. make the resulting <{ShipmentFootprint}> available to the [=Transport Service User=] through the PACT
    Network API (see [[#pcf-mapping-sf]]).

The [=Transport Service User=] CAN then derive the Transport Chain ([=TC=]) using the [=shipment id=], by
1. collecting the <{TCE|TCEs}> from all the [=Transport Operators=] and the [=Transport Service Organizers=] involved in 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 [[#example]].


## Data Transaction 2: TOC or HOC Data Exchange ## {#txn2}

This data transaction enables a [=Transport Service Organizer=] to receive [=TOC=] or [=HOC=] emission intensity data from a [=Transport Operator=].

The provision of emission intensity data at the [=TOC=] or [=HOC=] level would enable the [=Transport Service Organizer=] to collect the necessary information to calculate emissions according to the GLEC Framework and [[!ISO14083]].
It can 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).

To execute this transaction the [=Transport Operator=] or [=Transport Service Organizer=] MUST

1. calculate 1 or more TOC or HOC emission profiles in accordance with the [[!GLEC]] Framework and [[!ISO14083]], and then
2. make the resulting <{TOC|TOCs}> or <{HOC|HOCs}> available through the PACT Network API (see [[#pcf-mapping]]).

Note:
    Details on the definition and calculation of [=TOCs=] and [=HOCs=] are specified in [[!ISO14083]]
    and guidance is provided in the [[!GLEC]] Framework.


## Data Transaction 3: Transport Activity Data Exchange ## {#txn3}

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

To execute this transaction, the [=Transport Operator=] MUST

1. collect Transport Activity Data belonging to a consignment identified by the [=consignment id=].
2. make the <{TAD}> available through [[#action-tad]].

The [=Transport Service Organizer=] or [=Transport Service User=] CAN then retrieve the <{TAD|TADs}> using the [=consignment ids=].

Note:
      This data transaction is considered necessary by logistics parties, especially for SMEs,
      lacking the capabilities to make emissions data available. Through this transaction they can
      provide activity data to their customers.

# End-to-End Example # {#example}

Note: Non-normative section

This section provides an end-to-end example of how the data transactions ([[#txns]])
enable logistics emissions transparency for a single shipment.

The following hypothetical parties are involved:

: Transport Service User `S`
::
    A [=Transport Service User=] 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 ([[#txn1]]) to collect
    <{TCE|TCEs}>. Based on the collected <{TCE|TCEs}>, `S` can calculate the Transport Chain ([=TC=]) emissions.

: 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 ([[#txn1]])
    and Transaction 2 ([[#txn2]]).

    Through this, the operator is able to calculate <{TCE|TCEs}> and <{TOC|TOCs}>, and provide data to Transport Service User `S`.


: Transport Operator `A`
::
    A [=Transport Operator=] responsible for the first leg of the shipment.

    This Operator has a [=host system=] which is capable of calculating <{TCE}> and <{TOC}> 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 ([[#txn1]]).

: Transport Operator `B`
::
    Another [=Transport Operator=] responsible for the second leg of the shipment.

    This [=Transport Operator=] is capable of making <{TAD}> data available to the
    [=Transport Service Organizer=] Z.


## Data Transactions Executed ## {#example-txns}

Note: This hypothetical example currently ommits hub operations.

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


### Data Collection by Transport Service Organizer `Z` ### {#example-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 [[#txn1]] with Transport Operator `A` to collect the <{TCE|TCEs}>
    for the first leg of the shipment.
1. As Transport Operator `B` does not support [[#txn1]], `Z` performs [[#txn3]] with
    Transport Operator `B` to collect the <{TAD}> for the second leg of the shipment.
1. `Z` then calculates the <{TCE|TCEs}> for the second leg of the shipment based on
      the <{TAD}> data and modelled or default emission factors.

### Data Collection by Transport Service User `S` ### {#example-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 <{TCE|TCEs}> from `Z` using the [=shipment id=] and [[#txn1]], storing the resulting <{TCE|TCEs}> in e.g. its database.
1. `S` can further verify the <{TCE|TCEs}> by collecting the <{TOC|TOCs}> from `Z` using [[#txn2]].
1. `Z` can form the [=TC=] by adding up the <{TCE|TCEs}> from step 1.


## Example HTTP Calls ## {#example-http}

### Data Collection by Transport Service Organizer `Z` ### {#example-http-z}

To collect the <{TCE|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 shipment id, `Z` can retrieve the <{TCE|TCEs}> for
        the shipment of interest. The use of this functionality is not included in the example below.

The highlighted lines show the data exchanged according to the <{ShipmentFootprint}> data model.

<div class=example>
  Example HTTP Request (cURL) to collect TCE Data from Transport Operator A (please note that an actual API call would require authentication):
  <pre highlight='sh'>
      curl -X 'GET' \
      'https://api.transport-operator-a.com/2/footprints' \
      -H 'accept: application/json' \
      -H 'Authorization: Bearer [access-token]'
  </pre>

  Example response:

  <pre highlight='json' line-highlight="37-54" line-numbers>
  {
      "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://api.ileap.sine.dev/shipment-footprint.json",
          "data": {
            "mass": "87",
            "shipmentId": "1237890",
            "tces": [
              {
                "tceId": "abcdef",
                "prevTceIds": [],
                "tocId": "truck-40t-euro5-de",
                "shipmentId": "1237890",
                "mass": "87",
                "distance": {
                  "actual": "423"
                },
                "transportActivity": "36.801",
                "co2eWTW": "3.6801",
                "co2eTTW": "3.2801"
              }
            ]
          }
        }
      ]
    }
  </pre>
</div>


### Data Collection by Transport Service User `S` ### {#example-http-s}

To collect the TCE 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 shipment id, `Z` can retrieve the <{TCE|TCEs}>
        for the shipment of interest. The use of this functionality is not included in the example below.

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

<div class=example>
  Example HTTP Request (cURL) to collect TCE Data (please note that an actual API call would require authentication):
  <pre highlight='sh'>
      curl -X 'GET' \
      'https://api.transport-organizer.com/2/footprints' \
      -H 'accept: application/json' \
      -H 'Authorization: Bearer [access-token]'
  </pre>

  Example response:

  <pre highlight='json' line-highlight="37-66" line-numbers>
  {
      "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:shipment: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://api.ileap.sine.dev/shipment-footprint.json",
          "data": {
            "mass": "87",
            "shipmentId": "1237890",
            "tces": [
              {
                "tceId": "abcdef",
                "prevTceIds": [],
                "tocId": "truck-40t-euro5-de",
                "shipmentId": "1237890",
                "mass": "87",
                "distance": {
                  "actual": "423"
                },
                "transportActivity": "3.6801",
                "co2eWTW": "3.6801",
                "co2eTTW": "3.2801"
              },
              {
                "tceId": "ghijkl",
                "prevTceIds": [ "abcdef" ],
                "tocId": "operator-z-truck-89sdff",
                "shipmentId": "1237890",
                "mass": "87",
                "distance": {
                  "actual": "321"
                },
                "transportActivity": "27.927",
                "co2eWTW": "4.74759",
                "co2eTTW": "4.272831"
              }
            ]
          }
        }
      ]
    }
  </pre>
</div>



# Data Model # {#data-model}

The iLEAP data model of this chapter together with the data transactions ([[#txns]]) build on top of the [[!ISO14083|ISO 14083]] concepts of TOC, HOC, TCE, TC.

Additionally, the concept of transport activity data ([[#dt-tad|TAD]]) is added to facilitate reporting in case of missing data or limited emissions calculation capabilities from e.g. [=Transport Operators=].

Please, find more details on emissions calculation and the relantionship between the different concepts in the [[!GLEC]] Framework and [[!ISO14083]]).

The iLEAP Data Model is composed by five main data types: <{ShipmentFootprint}>, <{TCE}>, <{TOC}>,
<{HOC}>, and <{TAD}>.

<{ShipmentFootprint|ShipmentFootprints}> and <{TOC|TOCs}> can be exchanged independently as extensions to the PACT
Data Model ([[!PACTDX]]) (see [[!DATA-MODEL-EXTENSIONS]]) in a `ProductFootprint`.

<{TAD|TADs}> can be exchanged through a dedicated endpoint. This should only be used by [=Transport
Operators=] who cannot yet provide <{ShipmentFootprint|ShipmentFootprints}>, <{TOC|TOCs}>, nor <{HOC|HOCs}>.

## ShipmentFootprint ## {#dt-sf}

<dfn element>ShipmentFootprint</dfn> is a collection of 1
or more [=Transport Chain Elements=] (encoded as <{TCE|TCEs}>)
for a single [=shipment=], from a single entity (a [=Transport Operator=] or a [=Transport Service Organizer=]).

By collecting 1 or more <{TCE|TCEs}> for a shipment from [=Transport Operators=] and [=Transport Service Organizers=],
a [=Transport Service User=] can build the <{ShipmentFootprint}>. The <{ShipmentFootprint}> corresponds to the logistics emissions related to a full Transport Chain ([=TC=]).

To calculate a ShipmentFootprint, the [=Transport Service User=] MUST

- first receive <{TCE|TCEs}>  from [=Transport Operators=] and [=Transport Service Organizers=], linked to the shipment id for a single shipment in accordance with [[#dt-tce]],
    OR calculate <{TCE|TCEs}> from <{TOC|TOCs}>, <{HOC|HOCs}> or <{TAD}> from [=Transport Operators=] and [=Transport Service Organizers=].
- and then add up all <{TCE|TCEs}> that compose the full Transport Chain ([=TC=]) to derive the <{ShipmentFootprint}>.


### Data Attributes ### {#sf-attributes}

A <{ShipmentFootprint}> has the following properties:

<figure id="sf-properties-table" dfn-type="element-attr" dfn-for="ShipmentFootprint">
  <table class="data">
    <thead>
      <tr>
        <th>Property
        <th>Type
        <th>Req
        <th>Specification
    <tbody>
      <tr>
        <td><dfn>mass</dfn> : [=Decimal=]
        <td>String
        <td>M
        <td>The mass of the good (SI Unit `kilograms`) and the packaging provided for transport by the [=Transport Service User=], excluding any additional packaging or handling equipment used by the Transport Operator or Transport Service Organizer.
      <tr>
        <td><dfn>volume</dfn> : [=Decimal=]
        <td>String
        <td>O
        <td>The volume of the freight (SI Unit `cubic metre (CBM)`) and any packaging provided by the [=Transport Service User=].
      <tr>
        <td><dfn>numberOfItems</dfn>
        <td>Number
        <td>O
        <td>The number of units the shipment, including the goods transported and any packaging provided by the [=Transport Service User=], is composed of.
      <tr>
        <td><dfn>typeOfItems</dfn>
        <td>String
        <td>O
        <td>The type of units the shipment, including the goods transported and any packaging provided by the [=Transport Service User=], is composed of. For example, boxes, pallets, bottles, etc.
      <tr>
        <td><dfn>shipmentId</dfn>
        <td>String
        <td>M
        <td>The [=shipment id=] of the shipment related to this <{ShipmentFootprint}>.
      <tr>
        <td><dfn>tces</dfn>
        <td><{TCE}>[]
        <td>M
        <td>The non-empty array of [=TCEs=] relating to this shipment.

    </table>
    <figcaption>ShipmentFootprint properties</figcaption>
</figure>


## Transport Chain Element (<dfn element>TCE</dfn>) ## {#dt-tce}

The Data Type <{TCE}> models information related to a single [=Transport Chain Element=].

The data related to TCEs can be obtained from direct measurement (see [=Primary Data=]) or other measurements (see [=Secondary Data=]).

<{TCE|TCEs}> are typically calculated by [=Transport Operators=] and [=Transport Service Organizers=]. They are made available to [=Transport Service Users=] through
the <{ShipmentFootprint}> data type and the PACT Data Exchange Protocol. See [[#dt-sf]] and [[#pcf-mapping]] for details.


### Ordering of TCEs ### {#tce-ordering}

For reasons of transparency, traceability, auditability, and comprehensibility,
the recipients of TCE data ([=Transport Service User=] or [=Transport Service Organizer=]) SHOULD also receive the information
on the order in which the TCEs occurred during the transport of the shipment.

Order here means "happens-before" relationship between TCEs relative to other TCEs of the same <{ShipmentFootprint}>.

To facilitate this, the data model of TCEs includes the property <{TCE/prevTceIds}>.

If defined, <{TCE/prevTceIds}> MUST reference all the IDs (<{TCE/tceId}>) of the TCEs which happened *immediately* before the current TCE and <{ShipmentFootprint}>.
If the property is defined and the array is empty, the current TCE MUST be the first TCE of the shipment in relation to the <{ShipmentFootprint}>.

<div class=example>

  A [=Transport Service User=] procured the shipment of 2 containers to Rotterdam through a [=Transport Service Organizer=]. The organizer then makes a
  <{ShipmentFootprint}> available to the [=Transport Service User=], consisting of the following TCEs:

  1. Two TCEs with IDs `tce1234` and `tce567` for the first leg of the shipment comprising the transport of the 2 containers from the warehouse to the port.
      For both TCEs, <{TCE/prevTceIds}> must equal `[]` (the empty array).
  2. One TCE with ID `tce890` for the second leg of the shipment, which is the transport of the 2 containers from the port in Shanghai to the port of Rotterdam.
      For this TCE, <{TCE/prevTceIds}> must equal `["tce1234", "tce567"]`.
  3. And, last but not least, another TCE with ID `tceABC` for the hub operations at Rotterdam. For this TCE, <{TCE/prevTceIds}> must equal `["tce890"]`.


<figure>
  <img src="diagrams/tce-ordering.svg" height="80%" width="80%" >
  <figcaption>TCE happened-before relationship graph</figcaption>
</figure>

</div>


### Data Attributes ### {#tce-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.

<figure id="tce-properties-table" dfn-type="element-attr" dfn-for="TCE">
  <table class="data">
    <thead>
      <tr>
        <th>Property
        <th>Type
        <th>Req
        <th>Specification
    <tbody>
      <tr>
        <td><dfn>tceId</dfn>
        <td>String
        <td>M
        <td>The id of the [=Transport Chain Element=].

      <tr>
        <td><dfn>prevTceIds</dfn>
        <td>String[]
        <td>O
        <td>
              If defined, the <{TCE/tceId|tceIds}> of [=Transport Chain Element=] preceding the current TCE.
              See [[#tce-ordering]] for more information.

      <tr>
        <td><dfn>tocId</dfn>
        <td>String
        <td>
        <td>
              If defined, the id of the [=TOC=] used for the calculation of this <{TCE}>.

              Either <{TCE/tocId}> or <{TCE/hocId}> MUST be defined.
      <tr>
        <td><dfn>hocId</dfn>
        <td>String
        <td>
        <td>
              If defined, the id of the [=HOC=] used for the calculation of this <{TCE}>.

              Either <{TCE/tocId}> or <{TCE/hocId}> MUST be defined.

      <tr>
        <td><dfn>shipmentId</dfn>
        <td>String
        <td>M
        <td>The [=shipment id=] of the shipment related to this <{TCE}>.


      <tr>
        <td><dfn>consignmentId</dfn>
        <td>String
        <td>O
        <td>The [=consignment id=] of the consignment of corresponding to this <{TCE}>.

      <tr>
        <td><dfn>mass</dfn> : [=Decimal=]
        <td>String
        <td>M
        <td>The freight mass (SI derived Unit `kilograms`) and the packaging provided for transport by the Transport Service user, excluding any additional packaging or handling equipment used by the Transport Operator or Transport Service Organizer, in accordance with the [[!GLEC]] Framework.

      <tr>
        <td><dfn>packagingOrTrEqType</dfn>
        <td><{PackagingOrTrEqType}>
        <td>O
        <td>Category of relevant packaging or transport equipment units utilized for the transport of the consignment. See data type <{PackagingOrTrEqType}> for further information.

      <tr>
        <td><dfn>packagingOrTrEqAmount</dfn>
        <td>Number
        <td>O
        <td>Number of packaging or transport equipment units utilized to transport the related consignment by the [=Transport Operator=] or [=Transport Service Organizer=].

      <tr>
        <td><dfn>distance</dfn>
        <td><{GLECDistance}>
        <td>M
        <td>The [=distance=] between the origin and the destination of the activity related to the TCE.

      <tr>
        <td><dfn>origin</dfn>
        <td><{Location}>
        <td>O
        <td>The origin of the activity related to the TCE.

      <tr>
        <td><dfn>destination</dfn>
        <td><{Location}>
        <td>O
        <td>The destination of the activity related to the TCE.

      <tr>
        <td><dfn>transportActivity</dfn> : [=Decimal=]
        <td>String
        <td>M
        <td>
            The [=transport activity=] of the TCE (SI derived Unit `ton kilometers`)

            <div class=example>
                If the transport [=distance=] is `700` `kilometers` and the mass is `230` `kilograms`,
                then the value of this property MUST be `161` (`(700 kilometers * 230 kilograms) / 1000`).
            </div>

      <tr>
        <td><dfn>departureAt</dfn>
        <td>String
        <td>O
        <td>
              Timestamp of departure. The value MUST be a date and time string conforming to ISO 8601 with timezone UTC.

      <tr>
        <td><dfn>arrivalAt</dfn>
        <td>String
        <td>O
        <td>Timestamp of arrival. The value MUST be a date and time string conforming to ISO 8601 with timezone UTC.

      <tr>
        <td><dfn>flightNo</dfn>
        <td>String
        <td>O
        <td>Identification no of the IATA flight number.

      <tr>
        <td><dfn>voyageNo</dfn>
        <td>String
        <td>O
        <td>Identification no of a specific vessel operating on a specific route.

      <tr>
        <td><dfn>incoterms</dfn>
        <td>String
        <td>O
        <td>
            Incoterms are a set of internationally recognized rules defining the responsbilities of sellers and buyer in relation to the logistics activities between the parties.

            If defined, the value of this property MUST be one of the following:
            : EXW
            :: Ex Works

            : FCA
            :: Free Carrier

            : CPT
            :: Carriage Paid to

            : CIP
            :: Carriage and Insurance Paid to

            : DAP
            :: Delivered at Place

            : DPU
            :: Delivered at Place Unloaded

            : DDP
            :: Delivered Duty Paid

            : FAS
            :: Free Alongside Ship

            : FOB
            :: Free on Board

            : CFR
            :: Cost and Freight

            : CIF
            :: Cost, Insurance and Freight

      <tr>
        <td><dfn>co2eWTW</dfn> : [=Decimal=]
        <td>String
        <td>M
        <td>
              GHG emissions released to atmosphere during the process of producing, storing,
              processing and distributing an energy carrier for vehicle operation + GHG emissions
              released to atmosphere as a result of vehicle operation.
              The value MUST be calculated for the TCE with unit `kgCO2e`.

      <tr>
        <td><dfn>co2eTTW</dfn> : [=Decimal=]
        <td>String
        <td>M
        <td>
              GHG emissions released to atmosphere as a result of vehicle operation
              The value MUST be calculated for the TCE with unit `kgCO2e`.

      <tr>
        <td><dfn>noxTTW</dfn> : [=Decimal=]
        <td>String
        <td>O
        <td>
              Nitrogen oxide released to atmosphere as a result of vehicle operation.
              The value MUST be calculated for the TCE with unit `kg`.

      <tr>
        <td><dfn>soxTTW</dfn> : [=Decimal=]
        <td>String
        <td>O
        <td>
              Sulphur oxide released to atmosphere as a result of vehicle operation.
              The value MUST be calculated for the TCE with unit `kg`.

      <tr>
        <td><dfn>ch4TTW</dfn> : [=Decimal=]
        <td>String
        <td>O
        <td>
              Methane released to atmosphere as a result of vehicle operation.
              The value MUST be calculated for the TCE with unit `kg`.

      <tr>
        <td><dfn>pmTTW</dfn> : [=Decimal=]
        <td>String
        <td>O
        <td>
              Particulate matter (PM10 and PM2.5) released to atmosphere as a result of vehicle operation.
              The value MUST be calculated for the TCE with unit `kg`.

  </table>
  <figcaption>Properties of data type <{TCE}></figcaption>
</figure>


## Transport Operation Category (<dfn element>TOC</dfn>) ## {#dt-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=] SHOULD then make the <{TOC}> available through the PACT Network API as a `ProductFootprint` (see [[#pcf-mapping-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 values.

### Data Attributes ### {#toc-attributes}

The Data Type <{TOC}> has the following properties:

<figure id="toc-properties-table" dfn-type="element-attr" dfn-for="TOC">
  <table class="data">
    <thead>
      <tr>
        <th>Property
        <th>Type
        <th>Req
        <th>Specification
    <tbody>
      <tr>
        <td><dfn>tocId</dfn>
        <td>String
        <td>M
        <td>Unique id of the [=TOC=] relative to the [=Host system=].

      <tr>
        <td><dfn>isVerified</dfn>
        <td>Boolean
        <td>M
        <td>Indicates that the truthfulness of the GHG emissions value and related variables has been confirmed by a Validation and Verification Body (VVB), as declared in a Verification Statement. The VVB must follow a widely recognized standard for their GHG verification services (example: the ISO or ISAE standards). Verification should use [[!ISO14083]] as audit criteria.

      <tr>
        <td><dfn>isAccredited</dfn>
        <td>Boolean
        <td>M
        <td>(=certified) Indicates that the calculation methodology has been evaluated as compliant with [[!ISO14083]]:2023, as declared in an Accreditation (=Certification) certificate.

      <tr>
        <td><dfn>description</dfn>
        <td>String
        <td>O
        <td>Text description of the applicable TOC. Including mode of transport, contract type, equipment type, vehicle type, freight temperature, LTL/FTL etc

      <tr>
        <td><dfn>mode</dfn> : {{TransportMode}}
        <td>String
        <td>M
        <td>Mode of transport.

      <tr>
        <td><dfn>loadFactor</dfn> : [=Decimal=]
        <td>String
        <td>O
        <td>
            Ratio of the mass of the actual load to the maximum legally authorized load of a particular vehicle on a TOC level.
            It is applied to the loaded distance of the transport.

            The value of this property must be between `0` (excluding) and `1` (including).

      <tr>
        <td><dfn>emptyDistanceFactor</dfn> : [=Decimal=]
        <td>String
        <td>O
        <td>
            Ratio of the section of the route of a vehicle during which no freight is transported over the total distance (loaded plus empty distance) of a vehicle on a TOC level.

            The value of this property must be between `0` (including) and `1` (excluding).

      <tr>
        <td><dfn>temperatureControl</dfn>
        <td>String
        <td>O
        <td>
            Temperature control status of the TOC.

             If defined, the value of this property MUST be set to one of the following:
            : `ambient`
            :: For TOCs comprising the handling of non-temperature controlled freight only.

            : `refrigerated`
            :: For TOCs comprising the handling of refrigerated freight only.

            : `mixed`
            :: For TOCs comprising the handling of both ambient and refrigerated freight.
      <tr>
        <td><dfn>truckLoadingSequence</dfn>
        <td>String
        <td>O
        <td>
            Only for road. If defined, the value MUST be one of the following:

            : LTL
            :: For less than truck load, as defined in the [[!GLEC]] Framework. The sequence of pick-up & drop-off is PU-PU-DO-DO.
            : FTL
            :: For full truck load, as defined in the [[!GLEC]] Framework. The sequence of pick-up & drop-off is PU-DO-PU-DO.

     <tr>
        <td><dfn>airShippingOption</dfn>
        <td>String
        <td>O
        <td>
            Only for air transport. Indicates if the movement of freight is combined with passanger transport (belly freight), or a dedicated aircraft for the movement of freight (freighter).

            If defined, the value MUST be one of the following:
            : belly freight
            :: For freight combined with passanger transport.
            : freighter
            :: For freight moved by a dedicated aircraft.
     <tr>
        <td><dfn>flightLength</dfn>
        <td>String
        <td>O
        <td>
            Only for air transport. Indicates if the distance travelled is smaller or greater than 1500 km, as defined in the [[!GLEC]] Framework.

            If defined, the value MUST be one of the following:
            : short-haul
            :: For distances smaller than 1500 km.
            : long-haul
            :: For distances greater than 1500 km.

      <tr>
        <td><dfn>energyCarriers</dfn>
        <td><{EnergyCarrier}>[]
        <td>M
        <td>
            The non-empty array of [=EnergyCarriers=] used to generate mechanical movement or heat and to generate chemical or physical processes, as defined in the [[!GLEC]] Framework.
      <tr>
        <td><dfn>co2eIntensityWTW</dfn> : [=Decimal=]
        <td>String
        <td>M
        <td>
             The Coefficient relating specified transport activity with WTW GHG emissions with unit `kgCO2e` per <{TOC/co2eIntensityWTW}> as defined in the [[!GLEC]] Framework.
      <tr>
        <td><dfn>co2eIntensityTTW</dfn> : [=Decimal=]
        <td>String
        <td>M
        <td>
              The Coefficient relating specified transport activity with TTW GHG emissions with unit `kgCO2e` per <{TOC/co2eIntensityTTW}> as defined in the [[!GLEC]] Framework.
      <tr>
        <td><dfn>co2eIntensityThroughput</dfn>
        <td>String
        <td>M
        <td>
            Indicates the freight transport activity unit at the denominator of the <{TOC/co2eIntensityWTW}> and at the denominator of the <{TOC/co2eIntensityTTW}>. The value MUST be one of the following:

            : `TEUkm`
            :: For sea and inland waterways.

            : tkm
            :: For everything else.

            Advisement: The enumeration of throughputs will be evolved in future revisions. Account for this when implementing the validation of this property.
      <tr>
        <td><dfn>glecDataQualityIndex</dfn> : [0..4]
        <td>Number
        <td>O
        <td>
            The data quality index as defined in the [[!GLEC]] Framework

            The value of this property must be between `0` (including) and `4` (including).

            Issue: the exact calculation rules must be defined

  </table>
  <figcaption>Properties of data type `TOC`</figcaption>
</figure>


## Hub Operation Category (<dfn element>HOC</dfn>) ## {#dt-hoc}

The Data Type <{HOC}> contains [=HOC=] data. It is referenced in a [=Transport Chain Element=] through the <{TCE/hocId}> property.

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

### Data Attributes ### {#hoc-attributes}
The Data Type <{HOC}> has the following properties:

<figure id="hoc-properties-table" dfn-type="element-attr" dfn-for="HOC">
  <table class="data">
    <thead>
      <tr>
        <th>Property
        <th>Type
        <th>Req
        <th>Specification
    <tbody>
      <tr>
        <td><dfn>hocId</dfn>
        <td>String
        <td>M
        <td>The id of the <{HOC}>
      <tr>
        <td><dfn>description</dfn>
        <td>String
        <td>O
        <td>Text description of the applicable HOC. Including hub type, contract type, equipment type, freight temperature, etc
      <tr>
        <td><dfn>isVerified</dfn>
        <td>Boolean
        <td>M
        <td>Indicates that the truthfulness of the GHG emissions value and related variables has been confirmed by a Validation and Verification Body (VVB), as declared in a Verification Statement. The VVB must follow a widely recognized standard for their GHG verification services (example: the ISO or ISAE standards). Verification should use [[!ISO14083]] as audit criteria.
      <tr>
        <td><dfn>isAccredited</dfn>
        <td>Boolean
        <td>M
        <td>(=certified) Indicates that the calculation methodology has been evaluated as compliant with [[!ISO14083]]:2023, as declared in an Accreditation (=Certification) certificate.
      <tr>
        <td><dfn>hubType</dfn>
        <td>{{HubType}}
        <td>M
        <td>Type of Hub.
      <tr>
        <td><dfn>temperatureControl</dfn>
        <td>String
        <td>O
        <td>
            Temperature control status of the hub.

            If defined, the value of this property MUST be set to one of the following:
            : `ambient`
            :: For HOCs comprising the handling of non-temperature controlled freight only.

            : `refrigerated`
            :: For HOCs comprising the handling of refrigerated freight only.

            : `mixed`
            :: For HOCs comprising the handling of both ambient and refrigerated freight.

       <tr>
        <td><dfn>hubLocation</dfn>
        <td><{Location}>
        <td>O
        <td>The address of the hub.
      <tr>
        <td><dfn>inboundTransportMode</dfn>: {{TransportMode}}
        <td>{{TransportMode}}
        <td>O
        <td>Indicates the transport mode upstream the hub for this HOC.
      <tr>
        <td><dfn>outboundTransportMode</dfn>: {{TransportMode}}
        <td>{{TransportMode}}
        <td>O
        <td>Indicates the transport mode downstream the hub for this HOC.
      <tr>
        <td><dfn>packagingOrTrEqType</dfn>
        <td>String
        <td>O
        <td>Category of relevant packaging or transport equipment units utilized for the transport of the consignment. See data type <{PackagingOrTrEqType}> for further information.

      <tr>
        <td><dfn>packagingOrTrEqAmount</dfn>
        <td>Number
        <td>O
        <td>Number of packaging or transport equipment units utilized to transport the related consignment by the [=Transport Operator=] or [=Transport Service Organizer=].

      <tr>
        <td><dfn>energyCarriers</dfn>
        <td><{EnergyCarrier}>[]
        <td>M
        <td>
            The non-empty array of [=EnergyCarriers=] used to generate mechanical movement or heat and to generate chemical or physical processes, as defined in the [[!GLEC]] Framework.
      <tr>
        <td><dfn>co2eIntensityWTW</dfn> : [=Decimal=]
        <td>String
        <td>M
        <td>
             The Coefficient relating specified transport activity and WTW GHG emissions, with unit `kgCO2e` per <{HOC/co2eIntensityThroughput}> as defined in the [[!GLEC]] Framework.
 <tr>
        <td><dfn>co2eIntensityTTW</dfn> : [=Decimal=]
        <td>String
        <td>M
        <td>
              The Coefficient relating specified transport activity and TTW GHG emissions, with unit `kgCO2e` per <{HOC/co2eIntensityTTW}> as defined in the [[!GLEC]] Framework.

      <tr>
        <td><dfn>co2eIntensityThroughput</dfn>
        <td>String
        <td>M
        <td>
            Indicates the freight transport activity unit at the denominator of the <{HOC/co2eIntensityWTW}> and at the denominator of the <{HOC/co2eIntensityTTW}>. At the HOC level, the possible values are

            : `TEU`
            :: Leaving the hub for sea and inland waterways as outbound transport mode.

            : `tonnes`
            :: Leaving the hub.

            Advisement: The enumeration of throughputs will be evolved in future revisions. Account for this when implementing the validation of this property.

  </table>
  <figcaption>Properties of data type `HOC`</figcaption>
</figure>


## Transport Activity Data (<dfn element>TAD</dfn>) ## {#dt-tad}

The <dfn>Transport Activity Data </dfn> (<{TAD}>) data type contains activity
data, referring to a single consignment, leg, and mode of transport, or to a
single transshipment within a hub.

Each TAD CAN contain values for attributes which are categorial to the
operations of a fleet or hub (such as load factor or feedstock mix).
In this case, the values CAN be calculated from the actual data of more
than one consignment (“representative” or “average data”).

Note: Instead of exchanging the load factor for a single assignment, the load factor can be
calculated from a multitude of consignments following the principles of TOC calculation.

The TAD data type is designed for entities
([=Transport Operators=] or [=Transport Service Organizers=]) that lack
the capabilities to perform carbon emission calculations
(see [[#business-case-3|Business Case 3]]) or are
contractually obliged to exchange activity data with another party.

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

### Data Attributes ### {#tad-attributes}

The table below lists the properties defined for the <{TAD}> data type.

When exchanging it through the [[#action-tad|Action TransportActivityData]], it MUST be
encoded as a JSON object.

<figure id="tad-properties-table" dfn-type="element-attr" dfn-for="TAD">
  <table class="data">
    <thead>
      <tr>
        <th>Attribute Id
        <th>Type
        <th>Req
        <th>Description
    <tbody>
      <tr>
        <td><dfn>activityId</dfn>
        <td>String
        <td>M
        <td>The non-empty unique ID of this activity relative to the [=host system=].
      <tr>
        <td><dfn>consignmentIds</dfn>
        <td>String[]
        <td>M
        <td>The non-empty array of unique IDs of the consignments related to the activity (relative to the [=Host system=] and to the [=Data recipient=]).
      <tr>
        <td><dfn>distance</dfn>
        <td><{GLECDistance}>
        <td>M
        <td>The Distance between the origin and the destination of the activity.
      <tr>
        <td><dfn>mass</dfn> : [=Decimal=]
        <td>String
        <td>O
        <td>Mass of freight (SI derived Unit `kilograms`).
      <tr>
        <td><dfn>loadFactor</dfn> : [=Decimal=]
        <td>String
        <td>O
        <td>
            Ratio of the mass of the actual load to the maximum legally authorized load of a particular vehicle on a TOC level.
            It is applied to the loaded distance of the transport.

            The value of this property must be between `0` (excluding) and `1` (including).
      <tr>
        <td><dfn>emptyDistanceFactor</dfn> : [=Decimal=]
        <td>String
        <td>O
        <td>
            Ratio of the section of the route of a vehicle during which no freight is transported over the total distance (loaded plus empty distance) of a vehicle on a TOC level.

            The value of this property must be between `0` (including) and `1` (excluding).
      <tr>
        <td><dfn>origin</dfn>
        <td><{Location}>
        <td>M
        <td>The origin of the activity related to the Transport Activity.
      <tr>
        <td><dfn>destination</dfn>
        <td><{Location}>
        <td>M
        <td>The destination of the activity related to the Transport Activity.
      <tr>
        <td><dfn>departureAt</dfn>
        <td>String
        <td>M
        <td>
              Timestamp of departure. The value MUST be a date and time string conforming to ISO 8601 with timezone UTC.
      <tr>
        <td><dfn>arrivalAt</dfn>
        <td>String
        <td>M
        <td>Timestamp of arrival. The value MUST be a date and time string conforming to ISO 8601 with timezone UTC.
      <tr>
        <td><dfn>mode</dfn>
        <td>{{TransportMode}}
        <td>M
        <td>Mode of transport.
      <tr>
        <td><dfn>packagingOrTrEqType</dfn>
        <td>String
        <td>O
        <td>Category of relevant packaging or transport equipment units utilized for the transport of the consignment. See data type <{PackagingOrTrEqType}> for further information.
      <tr>
        <td><dfn>packagingOrTrEqAmount</dfn>
        <td>Number
        <td>O
        <td>Number of packaging or transport equipment units utilized to transport the related consignment by the [=Transport Operator=] or [=Transport Service Organizer=].

      <tr>
        <td><dfn>energyCarriers</dfn>
        <td><{EnergyCarrier}>[]
        <td>O
        <td>If defined, the non-empty array of [=EnergyCarriers=] used to generate mechanical
              movement or heat and to generate chemical or physical processes.

              This array MAY contain aggregated data from multiple consignments. In this case,
              the aggregation MUST follow principles from the [[!GLEC]] Framework.

    </table>
    <figcaption><{TAD}> properties</figcaption>
</figure>


## Additional Utility Data Types ## {#dt-utility-section}

### Data Type GLECDistance ### {#dt-glecdistance}

Data type `GLECDistance` represents a distance in kilometers 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 <dfn element>GLECDistance</dfn> MUST be defined:

<figure id="glecdistance-properties-table" dfn-type="element-attr" dfn-for="GLECDistance">
  <table class="data">
    <thead>
      <tr>
        <th>Attribute Id
        <th>Type
        <th>Req
        <th>Description
    <tbody>
      <tr>
        <td><dfn>actual</dfn> : [=Decimal=]
        <td>String
        <td>O
        <td>Distance between the origin and the destination of a consignment of
              freight or a vehicle, along a specified route (or from telematics), as defined in the [[!GLEC]] Framework.
      <tr>
        <td><dfn>gcd</dfn> : [=Decimal=]
        <td>String
        <td>O
        <td>[=Great Circle Distance=] between the origin and the destination, as defined in the [[!GLEC]] Framework.
      <tr>
        <td><dfn>sfd</dfn> : [=Decimal=]
        <td>String
        <td>O
        <td>[=Shortest Feasible Distance=] between the origin and the destination, as defined in the [[!GLEC]] Framework.

    </table>
    <figcaption><{GLECDistance}> properties</figcaption>
</figure>



### Data Type Location ### {#dt-location}

Properties of data type <dfn element>Location</dfn>:

<figure id="location-properties-table" dfn-type="element-attr" dfn-for="Location">
  <table class="data">
    <thead>
      <tr>
        <th>Attribute Id
        <th>Type
        <th>Req
        <th>Definition
    <tbody>
      <tr>
        <td><dfn>street</dfn>
        <td>String
        <td>O
        <td>Street of the location.

      <tr>
        <td><dfn>zip</dfn>
        <td>String
        <td>O
        <td>Postal code of the location.
      <tr>
        <td><dfn>city</dfn>
        <td>String
        <td>M
        <td>City of the location.
      <tr>
        <td><dfn>country</dfn>
        <td>Country
        <td>M
        <td>An ISO 3166-2 alpha-2 country code. See [https://wbcsd.github.io/data-exchange-protocol/v2/#iso3166cc](https://wbcsd.github.io/data-exchange-protocol/v2/#iso3166cc) for details.
      <tr>
        <td><dfn>iata</dfn>
        <td>iataCode
        <td>O
        <td>IATA code of airport. Applies only to (i) <{TCE|TCEs}> referring to a <{TOC}> with <{TOC/mode}> `Air`
            and (ii) <{TAD}> with <{TAD/mode}> `Air`.
      <tr>
        <td><dfn>locode</dfn>
        <td>locode
        <td>O
        <td>UN/LOCODE of the location.
      <tr>
        <td><dfn>uic</dfn>
        <td>uic
        <td>O
        <td>UIC Code of the location. Applies only to (i) <{TCE|TCEs}> referring to a <{TOC}> with <{TOC/mode}> `Rail`
            and (ii) <{TAD}> with <{TAD/mode}> `Rail`.
      <tr>
        <td><dfn>lat</dfn>
        <td>[=Decimal=]
        <td>O
        <td>Latitude of the location. If <{Location/lng}> is defined, so <{Location/lat}> MUST be defined.
      <tr>
        <td><dfn>lng</dfn>
        <td>[=Decimal=]
        <td>O
        <td>Longitude of the location.  If <{Location/lat}> is defined, so <{Location/lng}> MUST be defined.

    </table>
    <figcaption><{GLECDistance}> properties</figcaption>
</figure>


### Data Type <dfn enum>TransportMode</dfn> ### {#dt-transport-mode}

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:

<dl dfn-type="enum-value" dfn-for="TransportMode">

: <dfn>Road</dfn>
:: For transport mode `road`

: <dfn>Rail</dfn>
:: For transport mode `rail`

: <dfn>Air</dfn>
:: For transport mode `air`

: <dfn>Sea</dfn>
:: For transport mode `sea`

: <dfn>InlandWaterway</dfn>
:: For transport mode `inland waterway`

</dl>

NOTE: These transport modes are defined for TOC only. HOC transport modes are defined seperately.

### Data Type <dfn enum>HubType</dfn> ### {#dt-hub-type}

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:

<dl dfn-type="enum-value" dfn-for="HubType">

: <dfn>Transshipment</dfn>
:: Refers to hubs where transshipment is the main service (>80% of goods handled)

: <dfn>StorageAndTransshipment</dfn>
:: Refers to hubs where both transshipment and warehousing are relevant services

: <dfn>Warehouse</dfn>
:: Refers to hubs where warehousing is the main service (>80% of goods handled)

: <dfn>LiquidBulkTerminal</dfn>
:: Refers to terminals equiped to handle cargo in liquid and gaseous forms

: <dfn>MaritimeContainerTerminal</dfn>
:: Refers to hubs where maritime containers are handled

</dl>

### Data Type <dfn>Decimal</dfn> ### {#dt-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.


<div class=example>
  Example of the decimal numbers `10` and `-0.123` encoded in JSON:

  ```json
  "10"
  ```

  ```json
  "-0.123"
  ```
</div>

### Data Type <dfn>EnergyCarrier</dfn> ### {#dt-energy-carrier}

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 <dfn element>EnergyCarrier</dfn>:

<figure id="energy-carrier-properties-table" dfn-type="element-attr" dfn-for="EnergyCarrier">
  <table class="data">
    <thead>
      <tr>
        <th>Attribute Id
        <th>Type
        <th>Req
        <th>Definition
    <tbody>
      <tr>
        <td><dfn>energyCarrier</dfn>
        <td><{EnergyCarrierType}>
        <td>M
        <td>The substance used to generate mechanical movement or heat and to generate chemical or
        physical processes as per the [[!GLEC]] Framework. See data type <{EnergyCarrierType}> for further information.
      <tr>
        <td><dfn>feedstocks</dfn>
        <td><{Feedstock}>[]
        <td>O
        <td>If defined, the non-empty array of [=Feedstocks=] of the energy carrier. The sum total of the feedstock percentages MUST be smaller than or equal to 1.
      <tr>
        <td><dfn>energyConsumption</dfn> : [=Decimal=]
        <td>String
        <td>O
        <td>
            Amount of energy carrier consumed per transport activity, as defined for the TOC or HOC. If defined, <{EnergyCarrier/energyConsumptionUnit}>
            MUST be defined as well.
      <tr>
        <td><dfn>energyConsumptionUnit</dfn>
        <td>String
        <td>O
        <td>
            Unit of the energy consumed corresponding to the <{EnergyCarrier/energyConsumption}>.
            <{EnergyCarrier/energyConsumptionUnit}> MUST be defined if <{EnergyCarrier/energyConsumption}> is defined.

            Possible values are:
            : `l`
            :: For liters

            : `kg`
            :: For kilograms

            : `kWh`
            :: For kiloWatt-hour

            : `MJ`
            :: For MegaJoules

            Advisement: The enumeration of energy consumption units will be evolved in future revisions.
            Account for this when implementing the validation of this property.
      <tr>
        <td><dfn>emissionFactorWTW</dfn> : [=Decimal=]
        <td>String
        <td>O
        <td>
            The WTW fuel emission factor (certified) with unit `kgCO2e / energy consumption unit` (<{EnergyCarrier/energyConsumptionUnit}>).

            This property MUST be defined when <{EnergyCarrier}> is used in the context of a <{TOC}> or <{HOC}>.
      <tr>
        <td><dfn>emissionFactorTTW</dfn> : [=Decimal=]
        <td>String
        <td>O
        <td>
             The TTW fuel emission factor (certified) with unit `kgCO2e / energy consumption unit` (<{EnergyCarrier/energyConsumptionUnit}>).

            This property MUST be defined when <{EnergyCarrier}> is used in the context of a <{TOC}> or <{HOC}>.
    </table>
</figure>

### Data Type <dfn element>EnergyCarrierType</dfn> ### {#dt-energy-carrier-type}

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:

Advisement: The enumeration of energy carrier types 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




### Data Type <dfn>Feedstock</dfn> ### {#dt-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 <dfn element>Feedstock</dfn>:

<figure id="feedstock-properties-table" dfn-type="element-attr" dfn-for="Feedstock">
  <table class="data">
    <thead>
      <tr>
        <th>Attribute Id
        <th>Type
        <th>Req
        <th>Definition
    <tbody>
        <tr>
          <td><dfn>feedstock</dfn>
          <td>String
          <td>M
          <td>A feedstock of an [=EnergyCarrier=].

            The value MUST be one of the following:
            : Fossil
            :: Refers to fossil sources
            : Natural gas
            :: Refers to natural gas
            : Grid
            :: refers to grid electricity
            : Renewable electricity
            :: Refers to renewable sources of electricity
            : Cooking oil
            :: Refers to cooking (e.g., vegetable) oil

            Advisement: The enumeration of feedstocks will be evolved in future revisions.
            Account for this when implementing the validation of this property.

        <tr>
          <td><dfn>feedstockPercentage</dfn> : [0..1]
          <td>Number
          <td>O
          <td>Percentage of the feedstock in the total composition of energy carrier.
        <tr>
          <td><dfn>regionProvenance</dfn>
          <td>String
          <td>O
          <td>Country or region of provenance of the feedstock.
    </table>
</figure>

### Data Type <dfn element>PackagingOrTrEqType</dfn> ### {#dt-packaging-or-tr-eq-type}

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:

Advisement: 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

# HTTP REST API # {#http-rest-api}

A [=host system=] MUST implement:
1. The endpoint for the exchange of [=Transport Activity Data=] (see [[#action-tad]]); and
1. The exchange of <{ShipmentFootprint}>, <{TOC}>, and <{HOC}> as specified in [[#pcf-mapping]].

The exchange of logistics emissions data throught the [[#data-model]] presupposes the implementation of the HTTP REST API defined in [[!PACTDX]] (Chapter 6).

By relying on [[!PACTDX]] for the data exchange, the integration of logistics emissions data into existing [=host systems=]' software is simplified. In addition, this approach can further enhance and support the convergence of emissions transparency across sectors and initiatives.

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

## Action TransportActivityData ## {#action-tad}

Lists the [=data owner=]'s [=Transport Activity Data=] with [[#pagination]] and optional [[#filtering]]

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

### Filtering ### {#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
1. it CAN return an error response as defined in the [PACT Technical Specifications](https://wbcsd.github.io/tr/2023/data-exchange-protocol-20231207/#api-error-responses).
    For instance, a host system CAN return an error with code `NotImplemented` if it does not support a specific filter pair;
1. it CAN treat concatenated filters disjunctively, i.e., returning the union of the results of the individual filters.


### Pagination ### {#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;
1. the host system MUST return a `Link` header if there is additional [=Transport Activity Data=] ready to be retrieved, such that
    1. the `Link` header conforms to [[!RFC8288]];
    1. the value of the `rel` parameter is equal to `next`;
    1. the target IRI (RFC8288, section 3.1) of the `Link` header is absolute;
    1. 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 <dfn>pagination link</dfn>.

Upon a [=host system=] returning a [=pagination link=]:

1. a data recipient CAN call the pagination link more than once;
1. 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);
    1. MUST NOT return more data than requested in case [=Limit=] was defined by a [=data recipient=];
    1. MUST return a `Link` header conforming with the previous description in case there is additional Transport Activity Data  available;
1. if a response contains a second pagination link, upon the data recipient 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;
1. a pagination link MUST be valid for at least 180 seconds after creation;
1. a data recipient SHOULD retry calling the pagination link after the server returned an error;
    1. and SHOULD use a randomized exponential back-off strategy when retrying.

### Request Syntax ### {#action-tad-request}

<pre highlight=http>
GET <l>[=Subpath=]</l>/2/ileap/tad?<l>[=Filter=]</l>&<l>[=Limit=]</l> HTTP/1.1
host: <l>[=Hostname=]</l>
authorization: Bearer <l>[=BearerToken=]</l>
</pre>

: <dfn>Subpath</dfn>
:: If a host system uses a relative subpath, then the requesting data recipient MUST prepend this subpath.

: <dfn>Hostname</dfn>
:: The requesting data recipient MUST use the domain name of the host system.

: <dfn>BearerToken</dfn>
:: See [[!PACTDX]] section 6.3 Authentication Flow.

: <dfn>Filter</dfn>
::
    `Filter` is an OPTIONAL request parameter containing a filter statement.
    A <dfn>filter statement</dfn> 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 `&`.

    <div class=example>
      Get transport activity data with [=Feedstock=] `"Fossil"` and <{TAD/packagingOrTrEqType}> `"Pallet"`

      ```http
      GET /2/ileap/tad?feedstock=Fossil&packagingOrTrEqType=pallet HTTP/1.1
      ```
    </div>

: <dfn>Limit</dfn>
::
    `Limit` is an OPTIONAL request parameter. If defined,
      1. the name of the HTTP request parameter MUST be `limit` and
      2. the value MUST be a positive integer.

### Response Syntax ### {#action-tad-response}

Response without a `link` header:

<pre highlight=http>
HTTP/1.1 <l>[=TadStatusCode=]</l> <l>[=TadStatusText=]</l>
content-type: application/json
content-length: <l>[=ContentLength=]</l>

<l>[=TadResponseBody=]</l>
</pre>


Paginated response with a `link` header:

<pre highlight=http>
HTTP/1.1 <l>[=TadStatusCode=]</l> <l>[=TadStatusText=]</l>
content-type: application/json
content-length: <l>[=ContentLength=]</l>
link: <l>[=PaginationLink=]</l>; rel="next"

<l>[=TadResponseBody=]</l>
</pre>



With response parameters

: <dfn>TadStatusCode</dfn>
::
    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 [PACT Technical Specifications](https://wbcsd.github.io/tr/2023/data-exchange-protocol-20231207/#api-error-responsesm).

: <dfn>TadStatusText</dfn>
::
    The HTTP Status text conforming to the HTTP status code [=TadStatusCode=].

: <dfn>TadResponseBody</dfn>
::
    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](https://wbcsd.github.io/tr/2023/data-exchange-protocol-20231207/#accessdenied).

    If the host system does not accept the access token because it expired, the body SHOULD be an error response with code [TokenExpired](https://wbcsd.github.io/tr/2023/data-exchange-protocol-20231207/#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](https://wbcsd.github.io/tr/2023/data-exchange-protocol-20231207/#badrequest).

: <dfn>ContentLength</dfn>
:: The length of the Body. See [[!rfc9112]].

: <dfn>PaginationLink</dfn>
:: See [=pagination link=] and [[#pagination]].


## PACT Integration ## {#pcf-mapping}

The Data types defined in [[#data-model]] are specific to [[!ISO14083]] and the [[!GLEC]] Framework.

This section specifies the integration of the data types <{ShipmentFootprint}>, <{TOC}>, and <{HOC}> into the PACT Data Model ([[!PACTDX]] Chapter 4).
The integration of the data types <{ShipmentFootprint}>, <{TOC}>, and <{HOC}> is achieved by storing them as extensions to the PACT 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 [[#data-model]].
The list below contains the properties that were omitted for this reason.

Note: The extensions of one `ProductFootprint` CANNOT contain more than one iLEAP Data Type.

<figure id="ileap-pact-properties-mapping">
  <table class="data">
    <thead>
      <tr>
        <th>Attribute Id
        <th>Type
        <th>Req
        <th>Description
        <th>Source
    <tbody>
        <tr>
          <td>`validityPeriodStart` : [DateTime](https://wbcsd.github.io/tr/data-exchange-protocol/#datetime)
          <td>String
          <td>O
          <td>Determines the start of the validity period, ie., the time interval during which the ProductFootprint is declared as valid for use by a receiving data recipient.
          <td>[ProductFootprint/validityPeriodStart](https://wbcsd.github.io/tr/data-exchange-protocol/#element-attrdef-productfootprint-validityperiodstart)

        <tr>
          <td>`validityPeriodEnd` : [DateTime](https://wbcsd.github.io/tr/data-exchange-protocol/#datetime)
          <td>String
          <td>O
          <td>Determines the end (excluding) of the validity period, ie., the time interval during which the ProductFootprint is declared as valid for use by a receiving data recipient.
          <td>[ProductFootprint/validityPeriodEnd](https://wbcsd.github.io/tr/data-exchange-protocol/#element-attrdef-productfootprint-validityperiodend)
        <tr>
          <td>`assurance` : [Assurance](https://wbcsd.github.io/tr/data-exchange-protocol/#dt-assurance)
          <td>Object
          <td>O
          <td>If present, the Assurance information in accordance with the [[!PACT-FRAMEWORK]].
          <td>[CarbonFootprint/assurance](https://wbcsd.github.io/tr/data-exchange-protocol/#element-attrdef-carbonfootprint-assurance)
    </table>
</figure>

### ShipmentFootprint ### {#pcf-mapping-sf}

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

A ShipmentFootprint CAN be integrated into the PACT Data Model ([[!PACTDX]]) by storing a <{ShipmentFootprint}> as an extension (see [[!DATA-MODEL-EXTENSIONS]]) in a `ProductFootprint`.

For interoperability reasons, [[!PACTDX]]-related attributes MUST be derived from the <{ShipmentFootprint}> where possible. Details are specified in the [table](#pact-sf-mapping-table) below.

Note: Section [[#appendix-b-sf-example]] contains an example.

<figure id="pact-sf-mapping-table">
  <table class="data">
    <thead>
      <tr>
        <th>PACT Data Type
        <th>Property
        <th>Value Derivation
    <tbody>
      <tr>
        <td>ProductFootprint
        <td>`productIds`
        <td>
              MUST contain the shipment ID <{ShipmentFootprint/shipmentId}>, encoded as
              : `urn:pathfinder:product:customcode:vendor-assigned:shipment:<shipment id>`
              :: in case the [=transport service organizer=] has assigned a shipping id, or
              : `urn:pathfinder:product:customcode:buyer-assigned:shipment:<shipment id>`
              :: in case the [=transport service user=] has assigned a shipping id

              Note: `productIds` can contain multiple entries. If multiple or different
                      shipment ids are assigned to a single shipment, `productIds` CAN contain
                      all of them.

      <tr>
        <td>ProductFootprint
        <td>`productCategoryCpc`
        <td>
              MUST be equal to `83117`, the CPC code of logistics services.

      <tr>
        <td>CarbonFootprint
        <td>`declaredUnit`
        <td>
              MUST be set to `ton kilometer` conforming to the PACT Tech Specs.

              See [[!PACTDX]] Chapter 4 for further details.

      <tr>
        <td>CarbonFootprint
        <td>`unitaryProductAmount`
        <td>
              MUST equal the total ton kilometers over all TCEs (<{ShipmentFootprint/tces}>),
                    calculated by taking the sum of the ton kilometers over all TCEs (see property <{TCE/transportActivity}>)

      <tr>
        <td>CarbonFootprint
        <td>`productMassPerDeclaredUnit`
        <td>
              This property is OPTIONAL in the [[!PACTDX]] data Model but will become MANDATORY in v3.

              MUST equal the mass of the shipment (<{ShipmentFootprint/mass}>).

      <tr>
        <td>CarbonFootprint
        <td>`pCfExcludingBiogenic`
        <td>
              MUST be set to the total logistics emissions of the shipment calculated by taking the sum of the <{TCE/co2eWTW}>
              over all TCEs (<{ShipmentFootprint/tces}>).

              Advisement: Version 4 of the GLEC Framework will provide guidance on biogenic emissions. Updates to this property
              will be made after its release.
      <tr>
        <td>CarbonFootprint
        <td>`pCfIncludingBiogenic`
        <td>
              This property is OPTIONAL in the [[!PACTDX]] data Model.

              It SHOULD be kept undefined.

              Advisement: Version 4 of the GLEC Framework will provide guidance on biogenic emissions. Updates to this property
              will be made after its release.
      <tr>
        <td>CarbonFootprint
        <td>`fossilGhgEmissions`
        <td>
              See the specification for `pCfExcludingBiogenic` in this table.

      <tr>
        <td>CarbonFootprint
        <td>`fossilCarbonContent`
        <td>
              See the specification for `pCfExcludingBiogenic` in this table.

      <tr>
        <td>CarbonFootprint
        <td>`biogenicCarbonContent`
        <td>
              SHOULD be set to `"0"`

              Advisement: Version 4 of the GLEC Framework will provide guidance on biogenic emissions. Updates to this property
              will be made after its release.

      <tr>
        <td>CarbonFootprint
        <td>`packagingEmissionsIncluded`
        <td>
              See [[!PACTDX]] for further details.

              MUST be set to `false`.

      <tr>
        <td>CarbonFootprint
        <td>`primaryDataShare`
        <td>
              The relative share of logistics emissions for whose calculation primary data has been used.

              See [[!PACTDX]] and the PACT Framework ([[!PACT-FRAMEWORK]]) for further details.
      <tr>
        <td>DataModelExtension
        <td>`specVersion`
        <td>
              MUST be set `"2.0.0"`, the current version of [[DATA-MODEL-EXTENSIONS]].

      <tr>
        <td>DataModelExtension
        <td>`dataSchema`
        <td>
              MUST be set to `"https://api.ileap.sine.dev/shipment-footprint.json"`, the URL of the JSON schema for <{ShipmentFootprint}>.

              Advisement: The URL of the JSON schema will be updated in future revisions.

      <tr>
        <td>DataModelExtension
        <td>`documentation`
        <td>
              SHOULD be set. If set, its value MUST be `"https://sine-fdn.github.io/ileap-extension/"`.

      <tr>
        <td>DataModelExtension
        <td>`data`
        <td>
              MUST contain the <{ShipmentFootprint}> as a JSON object.
    </table>
    <figcaption>Mapping of PACT Data Model properties to <{ShipmentFootprint}> properties</figcaption>
</figure>

The `ProductFootprint` mandatory properties
[id](https://wbcsd.github.io/data-exchange-protocol/v2/#element-attrdef-productfootprint-id),
[specVersion](https://wbcsd.github.io/data-exchange-protocol/v2/#element-attrdef-productfootprint-specversion),
[version](https://wbcsd.github.io/data-exchange-protocol/v2/#element-attrdef-productfootprint-version),
[status](https://wbcsd.github.io/data-exchange-protocol/v2/#element-attrdef-productfootprint-status),
[companyName](https://wbcsd.github.io/data-exchange-protocol/v2/#element-attrdef-productfootprint-companyname),
[companyIds](https://wbcsd.github.io/data-exchange-protocol/v2/#element-attrdef-productfootprint-companyids),
[productDescription](https://wbcsd.github.io/data-exchange-protocol/v2/#element-attrdef-productfootprint-productdescription),
and
[productNameCompany](https://wbcsd.github.io/data-exchange-protocol/v2/#element-attrdef-productfootprint-productnamecompany)
cannot be derived from the `ShipmentFootprint` and MUST be provided by the data owner. Please follow
the links above for further details.

The `CarbonFootprint` mandatory properties
[characterizationFactors](https://wbcsd.github.io/data-exchange-protocol/v2/#element-attrdef-carbonfootprint-characterizationfactors),
[ipccCharacterizationFactorsSources](https://wbcsd.github.io/data-exchange-protocol/v2/#element-attrdef-carbonfootprint-ipcccharacterizationfactorssources),
[crossSectoralStandardsUsed](https://wbcsd.github.io/data-exchange-protocol/v2/#element-attrdef-carbonfootprint-crosssectoralstandardsused),
[crossSectoralStandars](https://wbcsd.github.io/data-exchange-protocol/v2/#element-attrdef-carbonfootprint-crosssectoralstandards),
[boundaryProcessesDescription](https://wbcsd.github.io/data-exchange-protocol/v2/#element-attrdef-carbonfootprint-boundaryprocessesdescription),
[referencePeriodStart](https://wbcsd.github.io/data-exchange-protocol/v2/#element-attrdef-carbonfootprint-referenceperiodstart),
[referencePeriodEnd](https://wbcsd.github.io/data-exchange-protocol/v2/#element-attrdef-carbonfootprint-referenceperiodend),
[exemptedEmissionsPercent](https://wbcsd.github.io/data-exchange-protocol/v2/#element-attrdef-carbonfootprint-exemptedemissionspercent),
and
[exemptedEmissionsDescription](https://wbcsd.github.io/data-exchange-protocol/v2/#element-attrdef-carbonfootprint-exemptedemissionsdescription)
cannot be derived from the `ShipmentFootprint` and MUST be provided by the data owner. Please follow
the links above for further details.

Any optional property that is not explicitly mentioned above MAY remain unset. All mandatory
properties that cannot be derived from `ShipmentFootprint` CAN be populated in a best-effort manner.

### TOC ### {#pcf-mapping-toc}

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

A TOC CAN be integrated into the PACT 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](#pact-toc-mapping-table) below.

Note: Section [[#appendix-b-toc-example]] contains an example.

<figure id="pact-toc-mapping-table">
  <table class="data">
    <thead>
      <tr>
        <th>PACT Data Type
        <th>Property
        <th>Value Derivation
    <tbody>
      <tr>
        <td>ProductFootprint
        <td>`productIds`
        <td>
              MUST contain the TOC ID <{TOC/tocId}>, encoded as
              : `urn:pathfinder:product:customcode:vendor-assigned:toc:<toc id>`
              :: in case the [=transport service organizer=] has assigned a toc id, or
              : `urn:pathfinder:product:customcode:buyer-assigned:toc:<toc id>`
              :: in case the [=transport service user=] has assigned a toc id

              Note: `productIds` can contain multiple entries. If multiple or different
                      toc ids are assigned to a single TOC, `productIds` CAN contain
                      all of them.
      <tr>
        <td>ProductFootprint
        <td>`productCategoryCpc`
        <td>
              MUST be equal to `83117`, the CPC code of logistics services.

      <tr>
        <td>CarbonFootprint
        <td>`declaredUnit`
        <td>
              MUST be set to `ton kilometer` conforming to the PACT Tech Specs.

              See [[!PACTDX]] Chapter 4 for further details.

      <tr>
        <td>CarbonFootprint
        <td>`unitaryProductAmount`
        <td>
              SHOULD be set to `"1"` so that the ProductFootprint represents the emissions per ton kilometer of the TOC.


      <tr>
        <td>CarbonFootprint
        <td>`productMassPerDeclaredUnit`
        <td>
              This property is OPTIONAL in the [[!PACTDX]] data Model but will become MANDATORY in v3.

              MUST be set to `"1"`.

      <tr>
        <td>CarbonFootprint
        <td>`pCfExcludingBiogenic`
        <td>
              MUST be set to the logistics emissions intensity of the TOC defined in <{TOC/co2eIntensityWTW}>.

              Advisement: Version 4 of the GLEC Framework will provide guidance on biogenic emissions. Updates to this property
              will be made after its release.

      <tr>
        <td>CarbonFootprint
        <td>`pCfIncludingBiogenic`
        <td>
              This property is OPTIONAL in the [[!PACTDX]] data Model.

              It SHOULD be kept undefined.

              Advisement: Version 4 of the GLEC Framework will provide guidance on biogenic emissions. Updates to this property
              will be made after its release.

      <tr>
        <td>CarbonFootprint
        <td>`fossilGhgEmissions`
        <td>
              See the specification for `pCfExcludingBiogenic` in this table.

      <tr>
        <td>CarbonFootprint
        <td>`fossilCarbonContent`
        <td>
              See the specification for `pCfExcludingBiogenic` in this table.

      <tr>
        <td>CarbonFootprint
        <td>`biogenicCarbonContent`
        <td>
              SHOULD be set to `"0"` (zero encoded as a string)

              Advisement: Version 4 of the GLEC Framework will provide guidance on biogenic emissions. Updates to this property
              will be made after its release.

      <tr>
        <td>CarbonFootprint
        <td>`packagingEmissionsIncluded`
        <td>
              See [[!PACTDX]] for further details.

              MUST be set to `false`.

      <tr>
        <td>CarbonFootprint
        <td>`primaryDataShare`
        <td>
              The relative share of logistics emissions for whose calculation primary data has been used.

              See [[!PACTDX]] and the PACT Framework ([[!PACT-FRAMEWORK]]) for further details.
      <tr>
        <td>DataModelExtension
        <td>`specVersion`
        <td>
              MUST be set `"2.0.0"`, the current version of [[DATA-MODEL-EXTENSIONS]].

      <tr>
        <td>DataModelExtension
        <td>`dataSchema`
        <td>
              MUST be set to `"https://api.ileap.sine.dev/toc.json"`, the URL of the JSON schema for <{TOC}>.

              Advisement: The URL of the JSON schema will be updated in future revisions.

      <tr>
        <td>DataModelExtension
        <td>`documentation`
        <td>
              SHOULD be set. If set, its value MUST be `"https://sine-fdn.github.io/ileap-extension/"`.

      <tr>
        <td>DataModelExtension
        <td>`data`
        <td>
              MUST contain the <{TOC}> as a JSON object.
  </table>
  <figcaption>Mapping of PACT Data Model properties to <{TOC}> properties</figcaption>
</figure>


The `ProductFootprint` mandatory properties
[id](https://wbcsd.github.io/data-exchange-protocol/v2/#element-attrdef-productfootprint-id),
[specVersion](https://wbcsd.github.io/data-exchange-protocol/v2/#element-attrdef-productfootprint-specversion),
[version](https://wbcsd.github.io/data-exchange-protocol/v2/#element-attrdef-productfootprint-version),
[status](https://wbcsd.github.io/data-exchange-protocol/v2/#element-attrdef-productfootprint-status),
[companyName](https://wbcsd.github.io/data-exchange-protocol/v2/#element-attrdef-productfootprint-companyname),
[companyIds](https://wbcsd.github.io/data-exchange-protocol/v2/#element-attrdef-productfootprint-companyids),
[productDescription](https://wbcsd.github.io/data-exchange-protocol/v2/#element-attrdef-productfootprint-productdescription),
and
[productNameCompany](https://wbcsd.github.io/data-exchange-protocol/v2/#element-attrdef-productfootprint-productnamecompany)
cannot be derived from the `TOC` and MUST be provided by the data owner. Please follow the links
above for further details.

The `CarbonFootprint` mandatory properties
[characterizationFactors](https://wbcsd.github.io/data-exchange-protocol/v2/#element-attrdef-carbonfootprint-characterizationfactors),
[ipccCharacterizationFactorsSources](https://wbcsd.github.io/data-exchange-protocol/v2/#element-attrdef-carbonfootprint-ipcccharacterizationfactorssources),
[crossSectoralStandardsUsed](https://wbcsd.github.io/data-exchange-protocol/v2/#element-attrdef-carbonfootprint-crosssectoralstandardsused),
[crossSectoralStandars](https://wbcsd.github.io/data-exchange-protocol/v2/#element-attrdef-carbonfootprint-crosssectoralstandards),
[boundaryProcessesDescription](https://wbcsd.github.io/data-exchange-protocol/v2/#element-attrdef-carbonfootprint-boundaryprocessesdescription),
[referencePeriodStart](https://wbcsd.github.io/data-exchange-protocol/v2/#element-attrdef-carbonfootprint-referenceperiodstart),
[referencePeriodEnd](https://wbcsd.github.io/data-exchange-protocol/v2/#element-attrdef-carbonfootprint-referenceperiodend),
[exemptedEmissionsPercent](https://wbcsd.github.io/data-exchange-protocol/v2/#element-attrdef-carbonfootprint-exemptedemissionspercent),
and
[exemptedEmissionsDescription](https://wbcsd.github.io/data-exchange-protocol/v2/#element-attrdef-carbonfootprint-exemptedemissionsdescription)
cannot be derived from the `TOC` and MUST be provided by the data owner. Please follow
the links above for further details.

Any optional property that is not explicitly mentioned above MAY remain unset. All mandatory
properties that cannot be derived from `TOC` CAN be populated in a best-effort manner.

### HOC ### {#pcf-mapping-hoc}

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

An HOC CAN be integrated into the PACT Data Model ([[!PACTDX]]) by storing an <{HOC}> as an
extension (see [[!DATA-MODEL-EXTENSIONS]]) in a `ProductFootprint`.

For interoperability reasons, several attributes of a `ProductFootprint` MUST be derived from the
<{HOC}>. This is specified in the [table](#pact-hoc-mapping-table) below.

Note: Section [[#appendix-b-hoc-example]] contains an example.

<figure id="pact-hoc-mapping-table">
  <table class="data">
    <thead>
      <tr>
        <th>PACT Data Type
        <th>Property
        <th>Value Derivation
    <tbody>
      <tr>
        <td>ProductFootprint
        <td>`productIds`
        <td>
              MUST contain the HOC ID <{HOC/hocId}>, encoded as
              : `urn:pathfinder:product:customcode:vendor-assigned:hoc:<hoc id>`
              :: in case the [=transport service organizer=] has assigned an hoc id, or
              : `urn:pathfinder:product:customcode:buyer-assigned:hoc:<hoc id>`
              :: in case the [=transport service user=] has assigned an hoc id

              Note: `productIds` can contain multiple entries. If multiple or different
                      hoc ids are assigned to a single HOC, `productIds` CAN contain
                      all of them.
      <tr>
        <td>ProductFootprint
        <td>`productCategoryCpc`
        <td>
              MUST be equal to `83117`, the CPC code of logistics services.

      <tr>
        <td>CarbonFootprint
        <td>`declaredUnit`
        <td>
              MUST be set to `kilogram` conforming to the PACT Tech Specs.

              See [[!PACTDX]] Chapter 4 for further details.

      <tr>
        <td>CarbonFootprint
        <td>`unitaryProductAmount`
        <td>
              MUST be set to `"1000"` so that the ProductFootprint represents the emissions of the HOC per tonne leaving the hub.

      <tr>
        <td>CarbonFootprint
        <td>`productMassPerDeclaredUnit`
        <td>
              This property is OPTIONAL in the [[!PACTDX]] data Model but will become MANDATORY in v3.

              MUST be set to `"1000"`.

      <tr>
        <td>CarbonFootprint
        <td>`pCfExcludingBiogenic`
        <td>
              MUST be set to the logistics emissions intensity of the HOC defined in <{HOC/co2eIntensityWTW}>.

              Note: The average weight of a container can be considered as 10 tonnes per `TEU`. For light containers, an
              estimate of 6 tonnes per `TEU` is appropriate, while heavy containers can be assumed to average 14.5 tonnes
              per `TEU`.

              Advisement: Version 4 of the GLEC Framework will provide guidance on biogenic emissions. Updates to this property
              will be made after its release.

      <tr>
        <td>CarbonFootprint
        <td>`pCfIncludingBiogenic`
        <td>
              This property is OPTIONAL in the [[!PACTDX]] data Model.

              It SHOULD be kept undefined.

              Advisement: Version 4 of the GLEC Framework will provide guidance on biogenic emissions. Updates to this property
              will be made after its release.

      <tr>
        <td>CarbonFootprint
        <td>`fossilGhgEmissions`
        <td>
              See the specification for `pCfExcludingBiogenic` in this table.

      <tr>
        <td>CarbonFootprint
        <td>`fossilCarbonContent`
        <td>
              See the specification for `pCfExcludingBiogenic` in this table.

      <tr>
        <td>CarbonFootprint
        <td>`biogenicCarbonContent`
        <td>
              SHOULD be set to `"0"` (zero encoded as a string)

              Advisement: Version 4 of the GLEC Framework will provide guidance on biogenic emissions. Updates to this property
              will be made after its release.

      <tr>
        <td>CarbonFootprint
        <td>`packagingEmissionsIncluded`
        <td>
              See [[!PACTDX]] for further details.

              MUST be set to `false`.

      <tr>
        <td>CarbonFootprint
        <td>`primaryDataShare`
        <td>
              The relative share of logistics emissions for whose calculation primary data has been used.

              See [[!PACTDX]] and the PACT Framework ([[!PACT-FRAMEWORK]]) for further details.

      <tr>
        <td>DataModelExtension
        <td>`specVersion`
        <td>
              MUST be set `"2.0.0"`, the current version of [[DATA-MODEL-EXTENSIONS]].

      <tr>
        <td>DataModelExtension
        <td>`dataSchema`
        <td>
              MUST be set to `"https://api.ileap.sine.dev/hoc.json"`, the URL of the JSON schema for <{HOC}>.

              Advisement: The URL of the JSON schema will be updated in future revisions.

      <tr>
        <td>DataModelExtension
        <td>`documentation`
        <td>
              SHOULD be set. If set, its value MUST be `"https://sine-fdn.github.io/ileap-extension/"`.

      <tr>
        <td>DataModelExtension
        <td>`data`
        <td>
              MUST contain the <{HOC}> as a JSON object.
  </table>
  <figcaption>Mapping of PACT Data Model properties to <{HOC}> properties</figcaption>
</figure>


The `ProductFootprint` mandatory properties
[id](https://wbcsd.github.io/data-exchange-protocol/v2/#element-attrdef-productfootprint-id),
[specVersion](https://wbcsd.github.io/data-exchange-protocol/v2/#element-attrdef-productfootprint-specversion),
[version](https://wbcsd.github.io/data-exchange-protocol/v2/#element-attrdef-productfootprint-version),
[status](https://wbcsd.github.io/data-exchange-protocol/v2/#element-attrdef-productfootprint-status),
[companyName](https://wbcsd.github.io/data-exchange-protocol/v2/#element-attrdef-productfootprint-companyname),
[companyIds](https://wbcsd.github.io/data-exchange-protocol/v2/#element-attrdef-productfootprint-companyids),
[productDescription](https://wbcsd.github.io/data-exchange-protocol/v2/#element-attrdef-productfootprint-productdescription),
and
[productNameCompany](https://wbcsd.github.io/data-exchange-protocol/v2/#element-attrdef-productfootprint-productnamecompany)
cannot be derived from the `HOC` and MUST be provided by the data owner. Please follow
the links above for further details.

The `CarbonFootprint` mandatory properties
[characterizationFactors](https://wbcsd.github.io/data-exchange-protocol/v2/#element-attrdef-carbonfootprint-characterizationfactors),
[ipccCharacterizationFactorsSources](https://wbcsd.github.io/data-exchange-protocol/v2/#element-attrdef-carbonfootprint-ipcccharacterizationfactorssources),
[crossSectoralStandardsUsed](https://wbcsd.github.io/data-exchange-protocol/v2/#element-attrdef-carbonfootprint-crosssectoralstandardsused),
[crossSectoralStandars](https://wbcsd.github.io/data-exchange-protocol/v2/#element-attrdef-carbonfootprint-crosssectoralstandards),
[boundaryProcessesDescription](https://wbcsd.github.io/data-exchange-protocol/v2/#element-attrdef-carbonfootprint-boundaryprocessesdescription),
[referencePeriodStart](https://wbcsd.github.io/data-exchange-protocol/v2/#element-attrdef-carbonfootprint-referenceperiodstart),
[referencePeriodEnd](https://wbcsd.github.io/data-exchange-protocol/v2/#element-attrdef-carbonfootprint-referenceperiodend),
[exemptedEmissionsPercent](https://wbcsd.github.io/data-exchange-protocol/v2/#element-attrdef-carbonfootprint-exemptedemissionspercent),
and
[exemptedEmissionsDescription](https://wbcsd.github.io/data-exchange-protocol/v2/#element-attrdef-carbonfootprint-exemptedemissionsdescription)
cannot be derived from the `HOC` and MUST be provided by the data owner. Please follow
the links above for further details.

Any optional property that is not explicitly mentioned above MAY remain unset. All mandatory
properties that cannot be derived from `HOC` CAN be populated in a best-effort manner.

# Conformance # {#conformance}

The iLEAP Technical Specifications are designed to be incrementally adopted and
realized in [=host systems=] for different stakeholder groups. Therefore,
there are 2 kinds of <dfn>iLEAP conformance</dfn> defined:

1. [=iLEAP Emissions Data Conformance=]
1. [=iLEAP Activity Data Conformance=]

For each kind of iLEAP Conformance, a host system achieves conformity by

1. realizing the normative statements and relevant test cases referenced
    in [[#ileap-conformance-matrix]] below,
2. successfully passing Bilateral Testing ([[#conformity-bilateral-testing]])
3. succesfully passing the [Automated Conformance Testing](https://act.sine.dev)

To achieve iLEAP Emissions Data Conformance, [=host systems=] are further REQUIRED to support the
following features:
1. fetching <{TAD}> from another host system and
2. using it to generate <{TOC}>, <{HOC}>, or <{ShipmentFootprint}> data.

It is RECOMMENDED for host systems to conform to both kinds of [=iLEAP conformance=].

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.

Advisement: Currently, iLEAP Conformance ensures interoperability and syntactic correctness. Future
updates will extend coverage to include semantic correctness, ensuring that emissions calculations
are performed accurately in end-to-end scenarios.

## Conformance Matrix ## {#ileap-conformance-matrix}

<figure>
  <table class="complex data">
    <thead>
      <tr>
        <th style="text-align: left">Test Case
        <th style="text-align: left">Conformance
    <tbody >
      <tr>
        <td style="text-align: left">All [PACT Required Test Cases](https://wbcsd.github.io/pact-conformance-testing/checklist.html#required-tests)
        <td rowspan="4"><dfn>iLEAP Emissions Data Conformance</dfn>

      <tr>
        <td style="text-align: left">[[#test-case-001]]

      <tr>
        <td style="text-align: left">[[#test-case-002]]

      <tr>
        <td style="text-align: left">[[#test-case-003]]

      <tr>
        <td style="text-align: left">[[#test-case-004]]
        <td rowspan="5"><dfn>iLEAP Activity Data Conformance</dfn>

      <tr>
        <td style="text-align: left">[[#test-case-005]]

      <tr>
        <td style="text-align: left">[[#test-case-006]]

      <tr>
        <td style="text-align: left">[[#test-case-007]]

      <tr>
        <td style="text-align: left">[[#test-case-008]]

  </table>
  <figcaption>iLEAP Conformance Matrix</figcaption>
</figure>


## Bilateral Testing ## {#conformity-bilateral-testing}

A Bilateral Test is an interoperability test where two different [=host system=]
implementations participate to verify conformance ([[#conformance]]) and their
ability to work together.

One system acts as the [=data owner=]. It is called the <dfn>target host system</dfn> and is the system under test.
The second system acts as the testing party.

Note:
  The objective of Bilateral Testing is to ensure that systems can effectively
  communicate despite having independent codebases.


## Submission ## {#conformity-submission}

Note: non-normative

Once a [=host system=] achieved [=iLEAP conformance=] in 1 or all kinds of iLEAP conformance,
the implementer is requested to reach out to the authors of this Technical Specifications to
apply for additional support, materials, and marketing opportunities.


# Appendix A: Changelog # {#changelog}

## Version 0.2.1-20250311 (2025-03-11) ## {#version-20250311}

- remove deprecated properties `TAD/energyCarrier` and `TAD/feedstocks`
- small typo fixes and text improvements
- add [[#conformance]] chapter
- improve [[#appendix-b]]'s guidance and readability
- finalize [[#test-case-004]]
- populate [[#test-case-005]], [[#test-case-006]], [[#test-case-007]], and [[#test-case-008]]

## Version 0.2.1-20250129 (2025-01-29) ## {#version-20250129}

- changes to <{TAD}> data type which are "backwards compatible" with the previous version:
    1. addition of optional property <{TAD/energyCarriers}> as a replacement for
    2. the now deprecated properties `TAD/energyCarrier` and `TAD/feedstocks`


## Version 0.2.1-20241211 (2024-12-11) ## {#version-20241211}

- add guidance on how to populate PACT's `DataModelExtension` data type in [[#pcf-mapping-sf]],
    [[#pcf-mapping-toc]], and [[#pcf-mapping-hoc]]
- remove outdated advisement from [[#appendix-b]]
- fix typos in `dataSchema` of [[#example-http]] and [[#appendix-b-hoc-example]]

## Version 0.2.1-20241113 (2024-11-13) ## {#version-20241113}

- add appendix [[#ileap-specific-conformance-tests]]

## Version 0.2.1-20241105 (2024-11-05) ## {#version-20241105}

- small typo fix in [[#pcf-mapping-toc]]: `fossilGhgEmissions` and `fossilCarbonContent` refer to
    `pCfExcludingBiogenic`

## Version 0.2.1-20240930 (2024-09-30) ## {#version-20240930}

- provide better guidance on [[#pcf-mapping]]

## Version 0.2.1-20240903 (2024-09-03) ## {#version-20240903}

- make application of <{Location/iata}> and <{Location/uic}> more explicit

## Version 0.2.1-20240813 (2024-08-13) ## {#version-20240813}

- add mentions to `HOC`s in [[#txn2]]
- add note to [[#pcf-mapping]] stating that one footprint cannot contain more than one iLEAP data type
- update note on `TEU` averages in [[#pcf-mapping-hoc]]

## Version 0.2.1-20240807 (2024-08-07) ## {#version-20240807}

- improved uniqueness definition in [=consignment id=] and [=shipment id=]
- use [=Decimal=] data type consistently
- add issues to <{ShipmentFootprint/numberOfItems}> and <{ShipmentFootprint/typeOfItems}> instead of
    common issue

## Version 0.2.1-20240716 (2024-07-16) ## {#version-20240716}

- addition of section [[#pcf-mapping-hoc]] and corresponding example [[#appendix-b-hoc-example]]
- small typo fixes (broken link in [[#pcf-mapping-toc]] and wrong highlights in [[#appendix-b]])

## Version 0.2.1-20240708 (2024-07-08) ## {#version-20240708}

- New "feature": OPTIONAL happened-before relationship between <{TCE|TCEs}> relative to a single shipment and <{ShipmentFootprint}>, enabled through the new property <{TCE/prevTceIds}>.
- Addition of the guidance chapter [[#tce-ordering]] to define the <{TCE/prevTceIds}> semantics

## Version 0.2.1-20240611 (2024-06-11) ## {#version-20240611}

- addition of section [[#document-statuses]]
- rewording of the introduction paragraphs of [[#introduction]]
- turn definition of <{EnergyCarrier/energyConsumption}> into "open" enumeration
- turn definition of <{TOC/co2eIntensityThroughput}> and <{HOC/co2eIntensityThroughput}> into "open"
    enumeration

## Version 0.2.0 Release (2024-06-05) ## {#version-20240605}

Stable Release including the following changes:

- reorganized and reworded chapter [[#business-cases]]
- updated introduction to the [[#dt-tad]] chapter
- replaced property `consignmentId` in <{TAD}> by an array of strings <{TAD/consignmentIds}>
    achieving coherence with introductory text
- rewording of chapter [[#business-cases]] and splitting of the business cases into individual subchapters
    - scope of business case 3 [[#business-case-3]] changed towards more clarity on use of TAD data
- reworded introduction at chapter [[#dt-tad]]
- updated the introduction to the [[#data-model]] chapter
- Consolidate American spelling
- Consolidate terminology in [[#txns]] diagram
- Renamed 2 properties in <{EnergyCarrier}>
    - `co2eIntensityWTW` renamed to <{EnergyCarrier/emissionFactorWTW}>
    - `co2eIntensityTTW` renamed to <{EnergyCarrier/emissionFactorTTW}>

## Version 0.2.0 Draft (2024-05-21) ## {#version-20240501}

Release Consultation Draft

- fixed typos and incorrect `productId` in examples
- `ServiceFootprint` renamed to `ShipmentFootprint` throughout this document

## Version 0.2.0-20240514 (2024-05-14) ## {#version-20240514}

- minor cleanups in section [[#dt-sf]]
- removal of stale `issues`

## Version 0.2.0-20240513 (2024-05-13) ## {#version-20240513}

Summary of changes:

- updated the mapping of a shipment id of a <{ShipmentFootprint}> into the PACT Data Model
- updated the mapping of a shipment id of a <{TOC}> into the PACT Data Model


## Version 0.1.0 (2024-05-13) ## {#version-0-1-0}

Summary: Initial release of the specification.


# Appendix B: Example PCFs with iLEAP Data embedded # {#appendix-b}

## ShipmentFootprint example ## {#appendix-b-sf-example}

A Product Footprint with a <{ShipmentFootprint}> highlighted:

<div class=example>
  <pre highlight='json' line-highlight="47-71" line-numbers>
    {
      "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:shipment:1237890"
      ],
      "productCategoryCpc": "83117",
      "productNameCompany": "Shipment with ID 1237890",
      "comment": "",
      "pcf": {
        "declaredUnit": "ton kilometer",
        "unitaryProductAmount": "36.801",
        "pCfExcludingBiogenic": "3.6801",
        "fossilGhgEmissions": "3.6801",
        "fossilCarbonContent": "0",
        "biogenicCarbonContent": "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": "Ecoinvent",
                "version": "3.9.1"
            }
        ],
        "exemptedEmissionsPercent": 0,
        "exemptedEmissionsDescription": "",
        "packagingEmissionsIncluded": true,
        "primaryDataShare": 56.12
      },
      "extensions": [
        {
          "specVersion": "2.0.0",
          "dataSchema": "https://api.ileap.sine.dev/shipment-footprint.json",
          "documentation": "https://sine-fdn.github.io/ileap-extension/",
          "data": {
              "mass": "87",
              "shipmentId": "1237890",
              "tces": [
                  {
                      "tceId": "abcdef",
                      "prevTceIds": [],
                      "tocId": "truck-40t-euro5-de",
                      "shipmentId": "1237890",
                      "mass": "87",
                      "distance": {
                          "actual": "423"
                      },
                      "transportActivity": "3.6801",
                      "co2eWTW": "3.6801",
                      "co2eTTW": "3.2801"
                  }
              ]
          }
        }
      ]
    }
  </pre>
</div>

## TOC example ## {#appendix-b-toc-example}

A Product Footprint with a <{TOC}> highlighted:

<div class=example>
  <pre highlight='json' line-highlight="47-71" line-numbers>
    {
      "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:toc:4561230"
      ],
      "productCategoryCpc": "83117",
      "productNameCompany": "TOC with ID 4561230",
      "comment": "",
      "pcf": {
        "declaredUnit": "ton kilometer",
        "unitaryProductAmount": "1",
        "pCfExcludingBiogenic": "3.6801",
        "fossilGhgEmissions": "3.6801",
        "fossilCarbonContent": "0",
        "biogenicCarbonContent": "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": "Ecoinvent",
                "version": "3.9.1"
            }
        ],
        "exemptedEmissionsPercent": 0,
        "exemptedEmissionsDescription": "",
        "packagingEmissionsIncluded": false,
        "primaryDataShare": 56.12
      },
      "extensions": [
        {
          "specVersion": "2.0.0",
          "dataSchema": "https://api.ileap.sine.dev/toc.json",
          "documentation": "https://sine-fdn.github.io/ileap-extension/",
          "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"
          }
        }
      ]
    }
  </pre>
</div>

## HOC example ## {#appendix-b-hoc-example}

A Product Footprint with a <{HOC}> highlighted:

<div class=example>
  <pre highlight='json' line-highlight="47-70" line-numbers>
    {
      "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 HOC with ID 7890123",
      "productIds": [
          "urn:pathfinder:product:customcode:vendor-assigned:hoc:7890123"
      ],
      "productCategoryCpc": "83117",
      "productNameCompany": "HOC with ID 7890123",
      "comment": "",
      "pcf": {
        "declaredUnit": "kilogram",
        "unitaryProductAmount": "1000",
        "pCfExcludingBiogenic": "3.6801",
        "fossilGhgEmissions": "3.6801",
        "fossilCarbonContent": "0",
        "biogenicCarbonContent": "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": "Ecoinvent",
                "version": "3.9.1"
            }
        ],
        "exemptedEmissionsPercent": 0,
        "exemptedEmissionsDescription": "",
        "packagingEmissionsIncluded": false,
        "primaryDataShare": 56.12
      },
      "extensions": [
        {
          "specVersion": "2.0.0",
          "dataSchema": "https://api.ileap.sine.dev/hoc.json",
          "documentation": "https://sine-fdn.github.io/ileap-extension/",
          "data": {
              "hocId": "7890123",
              "isVerified": true,
              "isAccredited": true,
              "hubType": "Warehouse",
              "temperatureControl": "refrigerated",
              "energyCarriers": [
                  {
                      "energyCarrier": "Diesel",
                      "co2eIntensityWTW": "3.6801",
                      "co2eIntensityTTW": "3.2801"
                  }
              ],
              "co2eIntensityWTW": "3.6801",
              "co2eIntensityTTW": "3.2801",
              "co2eIntensityThroughput": "tonnes"
          }
        }
      ]
    }
  </pre>
</div>

# Appendix C: iLEAP Conformance Testing # {#appendix-c}

Advisement: This appendix is a work in progress. All feedback is welcome.

In order to test the conformance of an iLEAP implementation, the following tests must be performed:

## PACT Conformance Tests ## {#pact-conformance-tests}

Since the iLEAP Technical Specifications were conceived as an extension to the PACT Data Model and
Data Exchange Protocol, any iLEAP conformant implementation must also implement [[!PACTDX]] v2.1.0 or above. For that
reason, the required tests in the [PACT Conformance Testing
Checklist](https://wbcsd.github.io/pact-conformance-testing/checklist.html#required-tests) should also be performed.

## iLEAP Specific Conformance Tests ## {#ileap-specific-conformance-tests}

The following tests are specific to the iLEAP Technical Specifications:

### Test Case 001: Get ProductFootprint with ShipmentFootprint ### {#test-case-001}

Tests the [=target host system=]'s ability to return `ProductFootprints` with `ShipmentFootprint`s as
extensions.

#### Request #### {#test-case-001-request}

A `ListFootprints` GET request must be sent to the `/2/footprints` endpoint of the test target host
system with a valid access token and the syntax specified in [PACT Tech Specs V2.2
§api-action-list-request](https://wbcsd.github.io/data-exchange-protocol/v2/#api-action-list-request).

#### Expected Response #### {#test-case-001-response}

The test [=target host system=] must respond with 200 OK with a JSON body containing a list of
`ProductFootprints` (as per the [PACT Tech Specs V2.2
§api-action-list-response](https://wbcsd.github.io/data-exchange-protocol/v2/#api-action-list-response)).
Those which include `productIds` with [the format specified for ShipmentFootprints](#pcf-mapping-sf)
must be conformant with the Data Model specified in [[#dt-sf]]. The relevant properties of the
`ProductFootprint` must also be confomant with the guidance provided in [[#pcf-mapping-sf]].

### Test Case 002: Get ProductFootprint with TOC ### {#test-case-002}

Tests the [=target host system=]'s ability to return `ProductFootprints` with `TOC`s as
extensions.

#### Request #### {#test-case-002-request}

A `ListFootprints` GET request must be sent to the `/2/footprints` endpoint of the test [=target host
system=] with a valid access token and the syntax specified in [PACT Tech Specs V2.2
§api-action-list-request](https://wbcsd.github.io/data-exchange-protocol/v2/#api-action-list-request).

#### Expected Response #### {#test-case-002-response}

The test [=target host system=] must respond with 200 OK with a JSON body containing a list of
`ProductFootprints` (as per the [PACT Tech Specs V2.2
§api-action-list-response](https://wbcsd.github.io/data-exchange-protocol/v2/#api-action-list-response)).

This list must include all the `TOCs` referenced in the `ShipmentFootprint`s returned in
[[#test-case-001]] (identified through the `productIds` field) and may include others.

All the `ProductFootprints` which include `productIds` with [the format specified for
TOCs](#pcf-mapping-toc) must be conformant with the Data Model specified in [[#dt-toc]]. The
relevant properties of the `ProductFootprint` must also be confomant with the guidance provided in
[[#pcf-mapping-toc]].

### Test Case 003: Get ProductFootprint with HOC ### {#test-case-003}

Tests the [=target host system=]'s ability to return `ProductFootprints` with `HOC`s as extensions.

#### Request #### {#test-case-003-request}

A `ListFootprints` GET request must be sent to the `/2/footprints` endpoint of the test [=target host
system=] with a valid access token and the syntax specified in [PACT Tech Specs V2.2
§api-action-list-request](https://wbcsd.github.io/data-exchange-protocol/v2/#api-action-list-request).

#### Expected Response #### {#test-case-003-response}

The test [=target host system=] must respond with 200 OK with a JSON body containing a list of
`ProductFootprints` (as per the [PACT Tech Specs V2.2
§api-action-list-response](https://wbcsd.github.io/data-exchange-protocol/v2/#api-action-list-response)).

This list must include all the `HOCs` referenced in the `ShipmentFootprint`s returned in
[[#test-case-001]] (identified through the `productIds` field) and may include others.

All the `ProductFootprints` which include `productIds` with [the format specified for
HOCs](#pcf-mapping-hoc) must be conformante with the Data Model specified in [[#dt-hoc]]. The
relevant properties of the `ProductFootprint` must also be confomant with the guidance provided in
[[#pcf-mapping-hoc]].

### Test Case 004: Get All TransportActivityData ### {#test-case-004}

Tests the [=target host system=]'s ability to return all `TransportActivityData`.

#### Request #### {#test-case-004-request}

A `TransportActivityData` GET request must be sent to the `/2/ileap/tad` endpoint of the test [=target
host system=] with a valid [=access token=] and the syntax specified in [[#action-tad-request]].

The access token must be obtained through the [PACT's Authentication Flow](https://wbcsd.github.io/tr/2023/data-exchange-protocol-20231207/#api-auth). This can be tested through PACT's Test Cases [001](https://wbcsd.github.io/pact-conformance-testing/checklist.html#tc001) and [002](https://wbcsd.github.io/pact-conformance-testing/checklist.html#tc002).

#### Expected Response #### {#test-case-004-response}

The test [=target host system=] must respond with 200 OK and a JSON body containing a list of
`TransportActivityData`, in conformance with [[#action-tad-response]] and following the data model
specified at [[#dt-tad]].

### Test Case 005: Get Filtered List of TransportActivityData ### {#test-case-005}

Tests the [=target host system=]'s ability to return a filtered list of `TransportActivityData`.

#### Request #### {#test-case-005-request}

A `TransportActivityData` GET request must be sent to the `/2/ileap/tad` endpoint of the test [=target
host system=] with a valid [=access token=] and the syntax specified in [[#action-tad-request]].

The request must include a query parameter [=Filter=]. Any property can be used as a filter, but we
recomend using {{TransportMode}}, iterating over all possible values:

- `GET /2/ileap/tad?mode=Road HTTP/1.1`
- `GET /2/ileap/tad?mode=Rail HTTP/1.1`
- `GET /2/ileap/tad?mode=Air HTTP/1.1`
- `GET /2/ileap/tad?mode=Sea HTTP/1.1`
- `GET /2/ileap/tad?mode=InlandWaterway HTTP/1.1`

The access token must be obtained through the [PACT's Authentication Flow](https://wbcsd.github.io/tr/2023/data-exchange-protocol-20231207/#api-auth). This can be tested through PACT's Test Cases [001](https://wbcsd.github.io/pact-conformance-testing/checklist.html#tc001) and [002](https://wbcsd.github.io/pact-conformance-testing/checklist.html#tc002).

#### Expected Response #### {#test-case-005-response}

For at least one filter, the test [=target host system=] must respond with 200 OK and a JSON body
containing a list of `TransportActivityData` matching the filter, in conformance with
[[#action-tad-response]] and following the data model specified at [[#dt-tad]].

### Test Case 006: Get Limited List of TransportActivityData ### {#test-case-006}

Tests the [=target host system=]'s ability to return a limited list of `TransportActivityData`.

#### Request #### {#test-case-006-request}

A `TransportActivityData` GET request must be sent to the `/2/ileap/tad` endpoint of the test
[=target host system=] with a valid [=access token=] and the syntax specified in
[[#action-tad-request]]. The request must include a query parameter [=Limit=] with value `1`.

The access token must be obtained through the [PACT's Authentication
Flow](https://wbcsd.github.io/tr/2023/data-exchange-protocol-20231207/#api-auth). This can be tested
through PACT's Test Cases
[001](https://wbcsd.github.io/pact-conformance-testing/checklist.html#tc001) and
[002](https://wbcsd.github.io/pact-conformance-testing/checklist.html#tc002).

#### Expected Response #### {#test-case-006-response}

The test [=target host system=] must respond with 200 OK and a JSON body containing one or less
`TransportActivityData`, in conformance with [[#action-tad-response]] and following the data model
specified at [[#dt-tad]].

If a [=pagination link=] is returned, it must conform to the syntax specified in
[[#action-tad-response]]. Upon calling that link, the [=target host system=] must respond wih 200 OK
and a JSON body containing one or more `TransportActivityData`.

If no [=pagination link=] is returned, a GET request sent to `/2/ileap/tad` (without query parameter
[=Limit=]) must respond with 200 OK and a JSON body containing exactly the same number of
`TransportActivityData` as that returned in the first request (including the query parameter
[=Limit=] with value `1`).

### Test Case 007: Attempt TransportActivityData with Invalid Token ### {#test-case-007}

Tests the [=target host system=]'s ability to handle a `TransportActivityData` request with an invalid
access token.

#### Request #### {#test-case-007-request}

A `TransportActivityData` GET request must be sent to the `/2/ileap/tad` endpoint of the test [=target
host system=] with an invalid access token and the syntax specified in [[#action-tad-request]].

#### Expected Response #### {#test-case-007-response}

The test [=target host system=] must respond with a 401 Unauthorized status code.

### Test Case 008: Attempt TransportActivityData with Expired Token ### {#test-case-008}

Tests the [=target host system=]'s ability to handle a `TransportActivityData` request with an expired
access token.

#### Request #### {#test-case-008-request}

A `TransportActivityData` GET request must be sent to the `/2/ileap/tad` endpoint of the test [=target
host system=] with an expired access token and the syntax specified in [[#action-tad-request]].

The access token must have been obtained through the [PACT's Authentication
Flow](https://wbcsd.github.io/tr/2023/data-exchange-protocol-20231207/#api-auth). This can be tested
through PACT's Test Cases
[001](https://wbcsd.github.io/pact-conformance-testing/checklist.html#tc001) and
[002](https://wbcsd.github.io/pact-conformance-testing/checklist.html#tc002).

#### Expected Response #### {#test-case-008-response}

The test [=target host system=] must respond with a 401 Unauthorized status code.

<pre class=biblio>
 {
    "GLEC": {
        "authors": [],
        "href": "https://smart-freight-centre-media.s3.amazonaws.com/documents/GLEC_FRAMEWORK_v3_UPDATED_12_10.pdf",
        "title": "Global Logistics Emissions Council Framework for Logistics Emissions Accounting and Reporting; v3.0 edition, revised and updated (2023).",
        "status": "LS",
        "publisher": "Smart Freight Centre (SFC)"
    },
    "ISO14083": {
      "authors": [],
      "title": "Greenhouse gases — Quantification and reporting of greenhouse gas emissions arising from transport chain operations",
      "href": "https://www.iso.org/standard/78864.html",
      "status": "International Standard published",
      "publisher": "International Organization for Standardization"
    },
    "PACTDX": {
      "authors": [
        "Martin Pompéry",
        "Cecilia Valeri"
      ],
      "title": "Technical Specifications for PCF Data Exchange (Version 2.1.0)",
      "href": "https://wbcsd.github.io/tr/2023/data-exchange-protocol-20231207/",
      "publisher": "WBCSD",
      "status": "CR"
    },
    "PACT-FRAMEWORK": {
      "authors": [],
      "href": "https://www.wbcsd.org/wp-content/uploads/2023/01/Pathfinder-Framework-Version-2.0.pdf",
      "title": "PACT Framework: Guidance for the Accounting and Exchange of Product Life Cycle Emissions (Version 2.0)",
      "status": "LS",
      "publisher": "WBCSD"
    },
    "DATA-MODEL-EXTENSIONS": {
      "authors": [],
      "href": "https://wbcsd.github.io/data-model-extensions/spec/",
      "title": "Technical Specification for Data Model Extensions",
      "status": "LS",
      "publisher": "WBCSD"
    }
  }
</pre>