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.

• Spec: https://sine-fdn.github.io/ileap-extension/
• Demo API: https://api.ileap.sine.dev

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

Key invariant

All numeric values are Decimal -- JSON strings matching ^-?\d+(\.\d+)?$. Never use JSON numbers for iLEAP numeric fields.

Data Transactions

• 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

TCE (Transport Chain Element)

TOC (Transport Operation Category)

HOC (Hub Operation Category)

EnergyCarrier

TAD (Transport Activity Data)

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

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

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

Supports $filter query parameter (OData v4 subset) and limit pagination with Link header.

Required filterable fields (GET /2/footprints):

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

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

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

PACT spec

The PACT v2.1.0 spec is at references/pact-spec-v2/index.bs (Bikeshed format, 2520 lines).

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

External References