ileap
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.
Best use case
ileap is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
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.
Teams using ileap should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/ileap/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How ileap Compares
| Feature / Agent | ileap | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
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.
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
# 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
`DataModelExtension`s 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)
```sh
# 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>"
```
```sh
# 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**:
```yaml
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](https://github.com/sine-fdn/impact-protocols/tree/main/demo-api#credentials).
### Step-by-step verification
```sh
# 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
```sh
# 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](https://github.com/sine-fdn/impact-protocols/tree/main/demo-api) | External reference server implementation (Rust/Rocket) |
| [Way Platform iLEAP Go](https://github.com/way-platform/ileap-go) | Way's iLEAP implementation in Go |Related Skills
way-magefile
Build tool for Go projects. Use when the user wants to create, edit, or understand Way-specific Magefiles, build targets, or automate Go project tasks.
protobuf
Use when working with Protocol Buffer (.proto) files, buf.yaml, buf.gen.yaml, or buf.lock. Covers proto design, buf CLI, gRPC/Connect services, protovalidate constraints, schema evolution, and troubleshooting lint/breaking errors.
prd
Generate a Product Requirements Document (PRD) for a new feature. Use when planning a feature, starting a new project, or when asked to create a PRD. Triggers on: create a prd, write prd for, plan this feature, requirements for, spec out.
clerk
Guide for authenticating a user via the Clerk Frontend API (FAPI) using username/password. Use when implementing the iLEAP Authentication Server Adapter or similar authentication backends that require programmatic username/password login via Clerk.
agents-md
This skill should be used when the user asks to "create AGENTS.md", "update AGENTS.md", "maintain agent docs", "set up CLAUDE.md", or needs to keep agent instructions concise. Guides discovery of local skills and enforces minimal documentation style.
workspace-surface-audit
Audit the active repo, MCP servers, plugins, connectors, env surfaces, and harness setup, then recommend the highest-value ECC-native skills, hooks, agents, and operator workflows. Use when the user wants help setting up Claude Code or understanding what capabilities are actually available in their environment.
ui-demo
Record polished UI demo videos using Playwright. Use when the user asks to create a demo, walkthrough, screen recording, or tutorial video of a web application. Produces WebM videos with visible cursor, natural pacing, and professional feel.
token-budget-advisor
Offers the user an informed choice about how much response depth to consume before answering. Use this skill when the user explicitly wants to control response length, depth, or token budget. TRIGGER when: "token budget", "token count", "token usage", "token limit", "response length", "answer depth", "short version", "brief answer", "detailed answer", "exhaustive answer", "respuesta corta vs larga", "cuántos tokens", "ahorrar tokens", "responde al 50%", "dame la versión corta", "quiero controlar cuánto usas", or clear variants where the user is explicitly asking to control answer size or depth. DO NOT TRIGGER when: user has already specified a level in the current session (maintain it), the request is clearly a one-word answer, or "token" refers to auth/session/payment tokens rather than response size.
skill-comply
Visualize whether skills, rules, and agent definitions are actually followed — auto-generates scenarios at 3 prompt strictness levels, runs agents, classifies behavioral sequences, and reports compliance rates with full tool call timelines
santa-method
Multi-agent adversarial verification with convergence loop. Two independent review agents must both pass before output ships.
safety-guard
Use this skill to prevent destructive operations when working on production systems or running agents autonomously.
repo-scan
Cross-stack source code asset audit — classifies every file, detects embedded third-party libraries, and delivers actionable four-level verdicts per module with interactive HTML reports.