7 min read · Updated 2026-05-05 · by TJO

IATA ONE Record 2.2.0 — what it is and how Skidd implements it

ONE Record is IATA's REST + JSON-LD replacement for Cargo-IMP — air cargo as a graph of LogisticsObjects rather than a stream of TELEX messages. Skidd ships an early-access ONE Record server (beta) today.

On this page
  1. What ONE Record is
  2. Why it matters
  3. Concrete example: the e-CSD
  4. What’s in the 2.2.0 spec
  5. What Skidd ships today
  6. How a partner consumes Skidd
  7. What’s genuinely hard about implementing ONE Record
  8. Where to go from here

What ONE Record is

ONE Record is IATA’s data-sharing standard for air cargo, designed to replace the flat-file Cargo-IMP world (FWB, FFM, FSU, FHL) with a single shared data model accessed over REST and serialised in JSON-LD.

Instead of every party shipping messages back and forth, every party publishes and consumes LogisticsObjects — structured resources for shipments, pieces, transport movements, parties, events — that link to each other through a shared ontology. A handler doesn’t receive an FWB; it reads (or subscribes to) the Shipment resource the forwarder published.

The 2.2.0 release of the spec landed in 2024 and is the version production deployments are conforming to today.

Why it matters

Three reasons handlers should care, in increasing order of importance:

  1. Less protocol surface area. One JSON-LD shape across every party, not seven different Cargo-IMP message types.

  2. Real-time by default. Subscriptions push notifications when a resource changes, instead of every party polling for FSUs.

  3. Ontology-grounded data. A Piece is the same thing whether the forwarder created it or the handler updated it — no dialect drift, no per-carrier translation layer, no field-by-field reconciliation. Disputes about who knew what when are answered by reading the version history of the resource.

The catch: the value compounds only when both sides of every interface speak ONE Record. That is happening, but unevenly — which is why every serious handler needs Cargo-IMP and ONE Record running side by side for the next several years.

Concrete example: the e-CSD

A useful illustration of the ontology-grounded approach is the electronic Customs Security Declaration. In Cargo-IMP the e-CSD rides inside the OCI segment of the FWB — a loose key-value bag that’s hard to validate, hard to query, and impossible to share selectively. In ONE Record the spec defines a dedicated SecurityDeclaration Logistics Object with named properties for each of the 15 e-CSD boxes (securityStatus, regulatedEntityIssuer, screeningMethods, issuedOn, issuedBy, etc.) linked to the Shipment via the securityDeclaration property.

The result: a customs auditor can subscribe to changes on the SecurityDeclaration only, with OAuth2-bounded scope, and get HMAC-signed notifications when the security status changes — without any access to the rest of the shipment. That selective-sharing-with-audit-trail story is exactly what messaging cannot do. See the e-CSD primer for the full field-by-field mapping.

What’s in the 2.2.0 spec

The pieces a handler implementation has to care about:

CapabilityWhat it is
LogisticsObjectsThe core resources: Shipment, Piece, TransportMovement, Party, ULD, Booking, etc. JSON-LD with @id URIs
Logistics EventsAppend-only events attached to objects — status changes, scans, transitions
Action RequestsAsynchronous requests one party makes against another’s resources (e.g. “please update the status to RCS”)
SubscriptionsWebhook-style push notifications when a resource changes; bearer-authenticated, HMAC-signed
Access DelegationsOAuth2-grounded delegation so party A can let party B act on its resources
NotificationsThe wire format for change events; JSON-LD over HTTPS POST
Well-known document/.well-known/one-record for service discovery

The spec also defines the data ontology — what fields a Shipment has, how a Piece relates to a ULD, how transport movements compose — via a published OWL ontology.

What Skidd ships today

The Skidd ONE Record server is in early-access beta (targeting 2.2.0; not yet spec-conformant). Per Skidd tenant you get:

  • A discoverable server at /.well-known/one-record describing capabilities and authentication
  • LogisticsObjects endpoints — GET, POST, PATCH — for every supported resource type
  • Logistics Events for append-only event capture and replay
  • Action Requests so partners can request state changes or data updates
  • Subscriptions so partners can subscribe to specific resources or types and receive HMAC-signed webhook notifications when they change
  • Access Delegations for OAuth2-bearer interop with partner servers
  • Bearer-token authentication on all reads and writes; per-token scope enforcement

What’s not yet in production:

  • The client side — outbound consumption of partner ONE Record servers is scaffolded but the full bidirectional bridge is on the roadmap (Phase E in our internal sequencing). For now, partners consume Skidd; Skidd consumes partners via Cargo-IMP.
  • CargoXML as a parallel transport — on the messaging roadmap behind the public Open API.

How a partner consumes Skidd

A typical integration:

  1. Discover. GET https://<tenant>.skidd.io/.well-known/one-record. Read supported types, auth endpoints, subscription URL.
  2. Authenticate. OAuth2 client-credentials flow against the auth endpoint. Receive a bearer token scoped to your delegation.
  3. Query. GET specific LogisticsObjects (/logistics-objects/{id}) or list (/logistics-objects?type=Shipment&since=...). JSON-LD response.
  4. Subscribe. POST a Subscription describing which resources you want change events for and your callback URL. Skidd POSTs HMAC-signed notifications when things change.
  5. Act. Submit Action Requests to ask Skidd’s tenant to do something on the resource (e.g. “please update piece-12’s status to FOH”).

A partner that already speaks ONE Record can be live against a Skidd tenant in an afternoon, not a month.

ONE Record subscription flow Partner posts a Subscription to Skidd's ONE Record server. When a LogisticsObject mutates, Skidd posts an HMAC-signed Notification to the partner callback. Partner forwarder · airline · customs auditor callback URL Skidd ONE Record ONE Record server /subscriptions /logistics-objects Shipment · Piece · SecurityDeclaration Mutation source 21-state engine acceptance UI FSU inbound PATCH from partner 1 · POST /subscriptions 2 · object mutates 3 · POST callback (HMAC-signed) control plane (request/response) data plane (notification)
Subscriptions invert the polling model: the partner registers once, then receives HMAC-signed POSTs whenever the underlying LogisticsObject changes.

What’s genuinely hard about implementing ONE Record

Three things that make ONE Record server implementations hard, all of which Skidd has solved — saying so explicitly because they are easy to overlook:

  1. JSON-LD is not just JSON. @context, @id, @type matter. A server that emits JSON without proper LD framing breaks the consumer’s graph parser. Skidd emits LD-framed responses with the IATA-published context.

  2. Subscriptions need exactly-once-ish delivery. Skidd retries on failure with exponential backoff, signs every notification with HMAC, includes a sequence number per subscription so consumers can detect gaps, and surfaces delivery health back to the partner that owns the subscription.

  1. Access Delegations are real OAuth2, not a checkbox. Token issuance, token refresh, scope enforcement, revocation, and audit are all production concerns. Skidd uses Supabase’s auth infrastructure for the OAuth2 layer and treats every delegation as auditable.

Where to go from here

If you’re a handler evaluating whether to switch from a Cargo-IMP-only platform: you don’t. You add ONE Record alongside. Both will run for years. Skidd ships both because that’s the honest state of the industry.

If you’re a partner integrating into Skidd over ONE Record: hit /.well-known/one-record on a tenant URL and the rest is documented inline.

For the protocol itself, IATA publishes the spec at iata.org/one-record and the ontology in OWL form on the IATA developer portal.