| name | ileap |
| description | iLEAP technical specs for exchanging logistics emissions data (ISO 14083 / GLEC Framework) via the PACT protocol. Use when implementing iLEAP APIs, data models (ShipmentFootprint, TCE, TOC, HOC, TAD), PACT DataModelExtensions, or conformance testing. Language-agnostic. |
iLEAP Technical Specifications
iLEAP extends the PACT Data Exchange Protocol with logistics emissions
data types conforming to ISO 14083 and the GLEC Framework v3.1.
Implementation Order
- PACT base: Authentication (OpenID discovery + OAuth2 Client
Credentials),
GET /2/footprints, GET /2/footprints/{id},
POST /2/events. See references/pact-implementation-guide.md.
- iLEAP extensions: Embed ShipmentFootprint, TOC, HOC as
DataModelExtensions in ProductFootprints.
- TAD endpoint:
GET /2/ileap/tad with filtering and pagination.
- Conformance: Run ACT against your server.
Architecture Overview
Roles
| Role | Description |
|---|
| Transport Service User | Purchases transport (e.g., shipper) |
| Transport Service Organizer | Provides transport, subcontracts operations (e.g., LSP) |
| Transport Operator | Carries out transport (e.g., carrier) |
Key invariant
All numeric values are Decimal -- JSON strings matching
^-?\d+(\.\d+)?$. Never use JSON numbers for iLEAP numeric fields.
Data Transactions
| DT | Data type | Provider | Consumer | Endpoint |
|---|
| DT#1 | ShipmentFootprint (TCEs) | Operator/Organizer | Service User | GET /2/footprints |
| DT#2 | TOC or HOC | Operator/Organizer | Organizer/User | GET /2/footprints |
| DT#3 | TAD | Operator | Organizer/User | GET /2/ileap/tad |
- DT#1: TCE-level emissions for a single shipment, wrapped in a ShipmentFootprint
- DT#2: Emission intensity data at TOC (transport) or HOC (hub) cluster level
- DT#3: Raw activity data (distance, mass, energy) for parties that cannot yet calculate emissions
Data Model Quick Reference
ShipmentFootprint
| Property | Type | Req | Description |
|---|
mass | Decimal | M | Freight mass in kg |
volume | Decimal | O | Freight volume in CBM |
shipmentId | String | M | Shipment identifier |
tces | TCE[] | M | Non-empty array of TCEs |
TCE (Transport Chain Element)
| Property | Type | Req | Description |
|---|
tceId | String | M | Unique TCE id |
prevTceIds | String[] | O | IDs of preceding TCEs (ordering) |
tocId | String | M* | TOC id (*one of tocId/hocId required) |
hocId | String | M* | HOC id (*one of tocId/hocId required) |
shipmentId | String | M | Shipment id |
mass | Decimal | M | Freight mass in kg |
distance | GLECDistance | M | Origin-destination distance |
transportActivity | Decimal | M | Transport activity in tkm |
co2eWTW | Decimal | M | WTW GHG emissions in kgCO2e |
co2eTTW | Decimal | M | TTW GHG emissions in kgCO2e |
TOC (Transport Operation Category)
| Property | Type | Req | Description |
|---|
tocId | String | M | Unique TOC id |
mode | TransportMode | M | Transport mode |
energyCarriers | EnergyCarrier[] | M | Energy carriers (shares must sum to 1) |
co2eIntensityWTW | Decimal | M | WTW intensity per transportActivityUnit |
co2eIntensityTTW | Decimal | M | TTW intensity per transportActivityUnit |
transportActivityUnit | String | M | "tkm" or "TEUkm" |
HOC (Hub Operation Category)
| Property | Type | Req | Description |
|---|
hocId | String | M | Unique HOC id |
hubType | HubType | M | Hub type |
energyCarriers | EnergyCarrier[] | M | Energy carriers (shares must sum to 1) |
co2eIntensityWTW | Decimal | M | WTW intensity per hubActivityUnit |
co2eIntensityTTW | Decimal | M | TTW intensity per hubActivityUnit |
hubActivityUnit | String | M | "tonnes" or "TEU" |
EnergyCarrier
| Property | Type | Req | Description |
|---|
energyCarrier | EnergyCarrierType | M | Enum value |
emissionFactorTTW | Decimal | M | kgCO2e per unit |
emissionFactorWTW | Decimal | M | kgCO2e per unit |
relativeShare | Decimal | M | Fraction of total energy (0–1). Must be "1" if only one carrier. |
TAD (Transport Activity Data)
| Property | Type | Req | Description |
|---|
activityId | String | M | Unique activity id |
consignmentIds | String[] | M | Consignment identifiers |
distance | GLECDistance | M | Origin-destination distance |
origin | Location | M | Origin location |
destination | Location | M | Destination location |
departureAt | DateTime | M | ISO 8601 UTC departure |
arrivalAt | DateTime | M | ISO 8601 UTC arrival |
mode | TransportMode | M | Transport mode |
Enum values
- TransportMode:
Road, Rail, Air, Sea, InlandWaterway
- HubType:
Transshipment, StorageAndTransshipment, Warehouse, LiquidBulkTerminal, MaritimeContainerTerminal
- EnergyCarrierType:
Diesel, HVO, Petrol, CNG, LNG, LPG, HFO, MGO, Aviation fuel, Hydrogen, Methanol, Electric
- PackagingOrTrEqType:
Box, Pallet, Container-TEU, Container-FEU, Container
- Feedstock:
Fossil, Natural gas, Grid, Renewable electricity, Cooking oil
JSON schemas
Located at references/ileap-data-model/schemas/:
shipment-footprint.json, toc.json, hoc.json, tad.jsonpcf-shipment-footprint.json, pcf-toc.json, pcf-hoc.json, pcf-tad.json
PACT Integration Rules
These are the most error-prone mappings when embedding iLEAP data into
PACT ProductFootprints.
Common rules (all iLEAP types)
productCategoryCpc: MUST always be "83117"packagingEmissionsIncluded: MUST be falsebiogenicCarbonContent: SHOULD be "0"extensions[].specVersion: MUST be "2.0.0"- One iLEAP extension per ProductFootprint (cannot mix SF + TOC etc.)
Per-type mapping
| Field | ShipmentFootprint | TOC | HOC |
|---|
productIds | urn:...:shipment:{shipmentId} | urn:...:toc:{tocId} | urn:...:hoc:{hocId} |
declaredUnit | "ton kilometer" | "ton kilometer" | "kilogram" |
unitaryProductAmount | sum(tces[].transportActivity) | "1" | "1000" |
pCfExcludingBiogenic | sum(tces[].co2eWTW) | co2eIntensityWTW | co2eIntensityWTW |
dataSchema URL | .../shipment-footprint.json | .../toc.json | .../hoc.json |
productIds URN format
urn:pathfinder:product:customcode:vendor-assigned:{type}:{id}
urn:pathfinder:product:customcode:buyer-assigned:{type}:{id}
Where {type} is shipment, toc, or hoc.
dataSchema URLs
| Type | URL |
|---|
| ShipmentFootprint | https://api.ileap.sine.dev/shipment-footprint.json |
| TOC | https://api.ileap.sine.dev/toc.json |
| HOC | https://api.ileap.sine.dev/hoc.json |
See references/pact-integration-examples.md for complete annotated
JSON examples of each type.
HTTP API
Authentication
- Discover token endpoint:
GET /.well-known/openid-configuration
- Obtain token:
POST /auth/token with Basic Auth + grant_type=client_credentials
- Use token:
Authorization: Bearer {token} on all API calls
See references/pact-implementation-guide.md for the full auth
contract including request/response formats.
PACT endpoints
| Method | Path | Description |
|---|
GET | /2/footprints | List ProductFootprints (with iLEAP extensions) |
GET | /2/footprints/{id} | Get single ProductFootprint |
POST | /2/events | Async event notifications |
Supports $filter query parameter (OData v4 subset) and limit
pagination with Link header.
Required filterable fields (GET /2/footprints):
| Field | Operators |
|---|
productCategoryCpc | eq |
productIds/any(id:(id eq '...')) | any/eq |
companyIds/any(id:(id eq '...')) | any/eq |
pcf/geographyCountry | eq |
created | gt, lt |
updated | gt, lt |
Combined filters using and must also be supported.
iLEAP endpoint
GET /2/ileap/tad?[filter params]&limit={n}
- Filtering: query parameters as key-value pairs (e.g.,
?mode=Road)
- Pagination:
limit param + Link: <url>; rel="next" header
- Response:
{ "data": [TAD, ...] }
Error codes
| Code | HTTP Status | Description |
|---|
AccessDenied | 403 | Invalid or missing token |
TokenExpired | 401 | Expired access token |
BadRequest | 400 | Malformed request |
NoSuchFootprint | 404 | Footprint ID not found |
NotImplemented | 400 | Unsupported filter or feature |
See references/known-issues.md for error code gotchas (e.g.,
NotImplemented is HTTP 400 not 501).
Conformance Testing & ACT
For a comprehensive guide on conformance tests, definitions, and requirements, please refer to the dedicated document:
references/conformance-tests.md
Conformance levels
- Emissions Data Conformance: DT#1 + DT#2 (ShipmentFootprint, TOC, HOC via
/2/footprints)
- Activity Data Conformance: DT#3 (TAD via
/2/ileap/tad)
iLEAP Test cases
| TC | Description | Endpoint | Expected |
|---|
| TC001 | Get ProductFootprint with ShipmentFootprint | GET /2/footprints | 200 + valid SF extension |
| TC002 | Get ProductFootprint with TOC | GET /2/footprints | 200 + valid TOC extension |
| TC003 | Get ProductFootprint with HOC | GET /2/footprints | 200 + valid HOC extension |
| TC004 | Get all TransportActivityData | GET /2/ileap/tad | 200 + valid TAD list |
| TC005 | Get filtered TAD | GET /2/ileap/tad?mode=Road | 200 + filtered results |
| TC006 | Get limited TAD | GET /2/ileap/tad?limit=1 | 200 + max 1 result |
| TC007 | TAD with invalid token | GET /2/ileap/tad | 403 AccessDenied |
| TC008 | TAD with expired token | GET /2/ileap/tad | 401 TokenExpired |
TC008 note: TC008 requires the server to issue short-lived tokens
so ACT can wait for expiry. Most test servers skip this by issuing
long-lived tokens — TC008 will then time out or fail.
PACT Test Cases (TC1-TC21)
The ACT tool also runs complementary PACT conformance test cases alongside iLEAP tests. Refer to references/pact-conformance-service/v2-test-cases-expected-results.md for full definitions.
Testability Classification:
- Locally testable (13 tests): TC1-TC8, TC15-TC16, TC18-TC20. Can run against local mock servers (
httptest.NewServer).
- Deployment-only (5 tests): TC9-TC11, TC17, TC21. Verify HTTPS enforcement; only apply to real deployments.
- Callback-dependent (3 tests): TC12-TC14. Require the server to POST back to a webhook URL, needing a mock listener.
Edge Cases:
- TC15 (Published Event): Requires a valid CloudEvent format (
type: "org.wbcsd.pathfinder.ProductFootprint.Published.v1", specversion: "1.0", with data.pfIds).
- TC20 (OData
$filter): The + character must be used as a space separator in the query string (not %20), as some implementations are sensitive to encoding.
Implementation Strategy: Unit Test Suite
When building an iLEAP-conformant API, strongly consider implementing the conformance test cases (TC001-TC008) and the PACT Required Test Cases (TC1-TC21) as a standalone integration or unit test suite within your language's native testing framework (e.g., go test, pytest, Jest).
Numbering Distinction:
iLEAP and PACT test cases use separate numbering schemes. To avoid confusion, local Go tests use:
TestTC001_... through TestTC008_... for iLEAP TCsTestPACT_TC01_... through TestPACT_TC20_... for PACT TCs
Why this matters:
- Regression Protection: Ensures that changes to core routing, auth, and data modeling don't accidentally break conformity before running the official ACT tool.
- SFC Certification: Conformance test cases are central to achieving SFC Certification. Automating these tests locally drastically shortens the feedback loop.
- Mocking: Building local test suites allows you to mock database layers and quickly test HTTP handler edge cases (e.g., pagination behaviors, token expiration, OData filtering) without spinning up the entire stack.
ACT (Automated Conformance Testing)
- Web UI: https://act.sine.dev
- CLI:
references/act/act.sh -- downloads and runs binary for current architecture (arm64/x86_64)
curl -sSf https://raw.githubusercontent.com/sine-fdn/act/main/act.sh |\
bash -s -- test -b "https://api.ileap.sine.dev" -u "<demo-user>" -p "<demo-password>"
curl -sSf https://raw.githubusercontent.com/sine-fdn/act/main/act.sh |\
bash -s -- test -b "<your-url>" -u "<user>" -p "<password>"
GitHub Actions integration:
act_test:
name: ACT Test
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Run ACT
run: |
set -o pipefail
curl -sSf https://raw.githubusercontent.com/sine-fdn/act/main/act.sh |\
bash -s -- test \
-b "${{ secrets.API_URL }}" \
-u "${{ secrets.ACT_USER }}" \
-p "${{ secrets.ACT_PASSWORD }}"
Important ACT constraints:
- Public URL Requirement: PACT tests require a publicly reachable server. ACT delegates PACT tests to an external service that must reach the API over the internet. Local
httptest servers cannot be tested with ACT directly.
- No iLEAP-only flag — ACT always runs both PACT and iLEAP test suites
- Known Failures:
- TC18/TC19 (OIDC): ACT crashes with a panic on local URLs. These tests pass on remote deployments.
- TC8 (Expired token): ACT's handling is unreliable; the equivalent logic is covered by iLEAP TC008. PACT TC8 and TC18 are known failures even on the SINE reference API (
api.ileap.sine.dev).
See references/act/README.md for full CLI options and coverage details.
Certification
SFC Certification Scheme extension for iLEAP Tool Providers
- Eligibility: must be SFC Certified + implemented DT#1 and DT#2
- Testing: ACT runs both PACT tests and iLEAP-specific tests
- Mandatory: DT#1 and DT#2 tests must pass
- Optional: DT#3 tests (recommended)
- Remediation: up to 3 attempts at 2-week intervals
- Validity: matches SFC Certification validity period
See references/pilot-certification.md for full certification process details.
Verification with SINE Demo API
The SINE Foundation hosts a public iLEAP-conformant server for testing.
Base URL
https://api.ileap.sine.dev
Credentials
Demo API credentials for the SINE reference server (including role-based accounts like transport_service_user and transport_service_organizer) are published in the SINE Foundation Demo API GitHub Repository.
Step-by-step verification
curl -s https://api.ileap.sine.dev/.well-known/openid-configuration | jq .
TOKEN=$(curl -s -X POST https://api.ileap.sine.dev/auth/token \
-u "<demo-user>:<demo-password>" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials" | jq -r .access_token)
curl -s https://api.ileap.sine.dev/2/footprints \
-H "Authorization: Bearer $TOKEN" | jq .
curl -s https://api.ileap.sine.dev/2/footprints/91715e5e-fd0b-4d1c-8fab-76290c46e6ed \
-H "Authorization: Bearer $TOKEN" | jq .
curl -s https://api.ileap.sine.dev/2/ileap/tad \
-H "Authorization: Bearer $TOKEN" | jq .
curl -s "https://api.ileap.sine.dev/2/ileap/tad?mode=Road" \
-H "Authorization: Bearer $TOKEN" | jq .
Navigating the Specs
iLEAP spec
The normative iLEAP spec is at references/ileap-extension/specs/index.bs
(Bikeshed format, 3291 lines).
| Section | Topic | Lines |
|---|
#introduction | Overview, PACT interop | 23-120 |
#definitions | ISO14083 and auxiliary terms | 125-237 |
#business-cases | Business cases 1-3 | 239-312 |
#txns | Data transactions DT#1-DT#3 | 315-387 |
#data-model | Data types (SF, TCE, TOC, HOC, TAD) | 624-1507 |
#dt-utility-section | GLECDistance, Location, enums | 1510-1897 |
#http-rest-api | TAD endpoint, filtering, pagination | 1899-2050 |
#pcf-mapping | PACT integration rules | 2052-2597 |
#conformance | Conformance levels | 2600-2730 |
#appendix-b | Example JSON (SF, TOC, HOC) | 2807-3049 |
#appendix-c | Conformance test cases TC001-TC008 | 3050-3244 |
PACT spec
The PACT v2.1.0 spec is at references/pact-spec-v2/index.bs
(Bikeshed format, 2520 lines).
| Section | Topic | Lines |
|---|
#intro | Introduction, scope | 16-70 |
#terminology | Term definitions | 73-121 |
#data-model | Data model overview | 138-161 |
#dt-pf | ProductFootprint properties | 163-334 |
#dt-carbonfootprint | CarbonFootprint properties | 337-646 |
#dt-datamodelextension | DataModelExtension | 827-852 |
#dt-declaredunit | DeclaredUnit enum | 1089-1121 |
#api-auth | Authentication flow | 1539-1564 |
#api-action-auth | Action Authenticate | 1591-1703 |
#api-action-list | Action ListFootprints | 1706-1861 |
#api-action-get | Action GetFootprint | 1863-1922 |
#api-action-events | Action Events | 1925-2134 |
#api-error-responses | Error codes table | 2135-2277 |
Grep patterns
grep -n '<dfn element>' references/ileap-extension/specs/index.bs
grep -n -A2 '<td>M$' references/ileap-extension/specs/index.bs
grep -n 'MUST be set to\|MUST equal\|MUST contain' references/ileap-extension/specs/index.bs
grep -n '<dfn>' references/pact-spec-v2/index.bs | head -40
grep -n '<td>M$' references/pact-spec-v2/index.bs
grep -n 'dfn>.*Denied\|dfn>.*Request\|dfn>.*Expired' references/pact-spec-v2/index.bs
Reference Files
Internal Skill References
| File | Purpose |
|---|
references/conformance-tests.md | iLEAP and PACT conformance tests definitions |
references/pact-conformance-service/v2-test-cases-expected-results.md | PACT Conformance Service – V2 Test Cases & Expected Results |
references/ileap-extension/specs/index.bs | Normative iLEAP spec (Bikeshed source) |
references/pact-spec-v2/index.bs | PACT v2.1.0 spec (Bikeshed source) |
references/pact-implementation-guide.md | PACT implementation steps (auth, endpoints, data model) |
references/known-issues.md | Implementation gotchas and workarounds |
references/demo-api-guide.md | iLEAP server implementation patterns |
references/openapi.json | OpenAPI contract (non-normative) |
references/ileap-data-model/schemas/*.json | JSON schemas for all iLEAP data types |
references/pact-data-model/schema/data-model-schema.json | PACT base data model schema |
references/pact-integration-examples.md | Annotated PACT integration JSON examples |
references/act/README.md | ACT CLI usage, test coverage |
references/act/act.sh | ACT runner script (detects arch, downloads binary) |
references/pilot-certification.md | SFC certification process for iLEAP |
references/whitepaper-v1.md | Strategic context only (not useful for implementation) |
External References
