Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

iLEAP conformance chapter #139

Merged
merged 5 commits into from
Mar 11, 2025
Merged

iLEAP conformance chapter #139

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
890e170
feat: add conformance chapter
raimundo-henriques Feb 17, 2025
04ec2ca
feat: add conformance chapter
raimundo-henriques Feb 17, 2025
d88c62e
fix: small typo
raimundo-henriques Mar 6, 2025
89abf87
feat: include simple pagination test in tc006
raimundo-henriques Mar 6, 2025
59ced6a
chore: update version date
raimundo-henriques Mar 11, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
231 changes: 211 additions & 20 deletions specs/index.bs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
<pre class='metadata'>
Title: iLEAP Technical Specifications (Version 0.2.1-20250129)
Title: iLEAP Technical Specifications (Version 0.2.1-20250311)
Shortname: ileap-extension
Status: LD
Status Text: Draft Technical Specification
Expand Down Expand Up @@ -140,7 +140,6 @@ status tags are:
: <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>
Expand Down Expand Up @@ -2502,8 +2501,117 @@ 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}

- 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:
Expand Down Expand Up @@ -2863,17 +2971,17 @@ In order to test the conformance of an iLEAP implementation, the following tests
## 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 be PACT Conformant. For that
reason, the tests in the [PACT Conformance Testing
Checklist](https://wbcsd.github.io/pact-conformance-testing/checklist.html) must be performed.
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
Tests the [=target host system=]'s ability to return `ProductFootprints` with `ShipmentFootprint`s as
extensions.

#### Request #### {#test-case-001-request}
Expand All @@ -2884,7 +2992,7 @@ system with a valid access token and the syntax specified in [PACT Tech Specs V2

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

The test target host system must respond with 200 OK with a JSON body containing a list of
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)
Expand All @@ -2893,15 +3001,18 @@ must be conformant with the Data Model specified in [[#dt-sf]]. The relevant pro

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

Expand All @@ -2915,15 +3026,17 @@ relevant properties of the `ProductFootprint` must also be confomant with the gu

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

Expand All @@ -2937,33 +3050,111 @@ relevant properties of the `ProductFootprint` must also be confomant with the gu

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

Issue: TBD
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}

Issue: TBD
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}

Issue: TBD
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}

Issue: TBD
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>
{
Expand Down