Skills
skills/way-platform/skills/ileap

ileap

SKILL.md

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

  1. PACT base: Authentication (OpenID discovery + OAuth2 Client Credentials), GET /2/footprints, GET /2/footprints/{id}, POST /2/events. See references/pact-implementation-guide.md.
  2. iLEAP extensions: Embed ShipmentFootprint, TOC, HOC as DataModelExtensions in ProductFootprints.
  3. TAD endpoint: GET /2/ileap/tad with filtering and pagination.
  4. 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.json
  • pcf-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 false
  • biogenicCarbonContent: 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

  1. Discover token endpoint: GET /.well-known/openid-configuration
  2. Obtain token: POST /auth/token with Basic Auth + grant_type=client_credentials
  3. 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

  1. Emissions Data Conformance: DT#1 + DT#2 (ShipmentFootprint, TOC, HOC via /2/footprints)
  2. 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 TCs
  • TestPACT_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)
# Run against demo API (Check SINE Foundation Demo API for current credentials)
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>"

# Run against your own API
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

# 1. Discover OpenID configuration
curl -s https://api.ileap.sine.dev/.well-known/openid-configuration | jq .

# 2. Obtain access token
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)

# 3. List all footprints
curl -s https://api.ileap.sine.dev/2/footprints \
  -H "Authorization: Bearer $TOKEN" | jq .

# 4. Get a specific footprint by ID
curl -s https://api.ileap.sine.dev/2/footprints/91715e5e-fd0b-4d1c-8fab-76290c46e6ed \
  -H "Authorization: Bearer $TOKEN" | jq .

# 5. List transport activity data
curl -s https://api.ileap.sine.dev/2/ileap/tad \
  -H "Authorization: Bearer $TOKEN" | jq .

# 6. Filter TAD by transport mode
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

# iLEAP: find a data type definition
grep -n '<dfn element>' references/ileap-extension/specs/index.bs

# iLEAP: find all required properties for a type
grep -n -A2 '<td>M$' references/ileap-extension/specs/index.bs

# iLEAP: find PACT mapping rules
grep -n 'MUST be set to\|MUST equal\|MUST contain' references/ileap-extension/specs/index.bs

# PACT: find property definitions
grep -n '<dfn>' references/pact-spec-v2/index.bs | head -40

# PACT: find all mandatory properties
grep -n '<td>M$' references/pact-spec-v2/index.bs

# PACT: find error codes
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

Link Purpose
SINE Foundation Demo API External reference server implementation (Rust/Rocket)
Way Platform iLEAP Go Way's iLEAP implementation in Go
Weekly Installs
14
Repository
way-platform/skills
GitHub Stars
2
First Seen
Feb 18, 2026
Security Audits
Gen Agent Trust HubFail
SocketFail
SnykFail
Installed on
gemini-cli14
github-copilot14
codex14
kimi-cli14
cursor14
opencode14