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)

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.

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

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)

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.

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:

• PACT tests require a publicly reachable server — ACT delegates PACT tests to an external service that must reach the API over the internet
• No iLEAP-only flag — ACT always runs both PACT and iLEAP test suites
• 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