ileap

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.

• 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

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)

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.

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 as a standalone integration or unit test suite within your language's native testing framework (e.g., go test, pytest, Jest).

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:

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

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/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