IATA One Record Integration

Skip key takeaways

Updated September 21, 2026

• Publish and grant replaces sending a document Each party keeps its own logistics objects on its own server and hands out a URI, so access can be changed or revoked after the fact.
• LogisticsEvent is not a LogisticsObject The ontology links events to objects through a separate property and gives them their own endpoint, which a class diagram summary easily hides.
• A node holding only @id is how the network actually links JSON-LD's node reference is the mechanism that lets a Waybill point at a Shipment hosted on someone else's server without embedding it.
• Reading is mandatory, creating is a private choice Every logistics object must answer a GET request, while only its holder may expose any way at all to create one.
• The working draft names its own version inconsistently Four files state four different numbers for the same API, so an integration should pin a version per file rather than trust a single current release.

Copy takeaways

IATA One Record integration begins with a decision most cargo systems make without noticing: whether a shipment's record travels as a document or stays where it was created and gets shared as a link. IATA states the destination on its program page: "The vision for ONE Record is an end-to-end digital logistics and transport supply chain where data is easily and transparently exchanged in a digital ecosystem of air cargo stakeholders, communities, and data platforms." The definition that follows is closer to what an integration team builds against: "ONE Record is a standard for data sharing and creates a single record view of the shipment. This ONE Record standard defines a common data model for the data that is shared via standardized and secured web API." (IATA, ONE Record program page)

In short: ONE Record replaces sending files with publishing objects and granting access by URI. Its ontology has seven core classes that do not sit at one level, and treating them as if they did breaks an integration before it ships. Coexisting with Cargo-XML is a mapping IATA has already published for eight named messages, not a wholesale replacement of EDI. And the specification itself is a moving target: four artifacts state four different version strings, which an integration has to survive rather than resolve.

Why a shipment needs one record instead of many documents

IATA scopes ONE Record into three specified parts. The data model half "provides the air cargo industry with a standard data structure for data exchange using JSON-LD that facilitates data integration with existing and new data services". The API half "specifies the interface and interaction of the web API or Application Programming Interface that allows airlines and their partners to connect their system directly using best in class web technologies". Security is the third half, running on an industry-wide, federated trust network for identification, authentication and confidentiality between parties. (IATA, ONE Record program page) The undated background IATA gives is the e-freight program, where "the e-AWB is now used for more than 2 out of 3 shipments", a figure with no stated measurement period, so it reads as a claim made on the page rather than a live number.

The repository that hosts the specification describes its own contents plainly: "This repository contains the data model, ontology, API & Security specifications of ONE Record." (IATA-Cargo/ONE-Record, repository README) One folder that README names does not actually exist on the branch it documents, a discrepancy this guide returns to under its own heading below.

Publish and grant is the model behind the standard

IATA states the model directly: "Data is shared by a data owner who is in full control of data quality. Data stays at the source and the owner determines who may or may not access their data", so that "Each party is able to share data of the shipment with relevant parties, ensuring enhanced visibility and transparency". (IATA, ONE Record program page) Nothing moves by default; a party keeps what it created and decides, object by object, who else gets to read it.

The portal names the role that follows from creating an object rather than from owning the shipment: "The holder of a Logistics Object is the one who created it and thus has control over it", though "The holder of a Logistics Object might be even the owner of the data. The term holder does not include legal topics such as data governance, ownership, data stewardship or data custodian." Everyone else with an interest is a user: "A user of a Logistics Object is anyone other than the holder and who has an interest in the Logistics Object." (Portal, API Specification, Concepts) The glossary names the two roles a network runs on, a publisher, "The Party that makes their Logistics Objects available through a ONE Record Server", and a subscriber, "The Party that subscribes to Logistics Objects in order to receive updates automatically". (Portal, API Specification, Glossary)

Access is a decision the hosting server makes, not a property of the network: the server "that hosts the logistics objects will determine whether to grant access." The next sentence is the one that licenses the whole idea of sharing a link rather than a document, describing the ordinary path a shipment takes: "Typically, when an participant creates a LogisticsObject and makes it available via its ONE Record API, the IoL participant will share the URI of that LogisticsObject with another IoL participant and grant them access by default." A URI is handed over once, and the grant behind it moves independently of any file: "The ONE Record standard allows parties to change or revoke these access rights to their data whenever they wish." (Portal, API Specification, Access Delegations) Revocable access rather than a copy that already left is what a sent PDF or an EDI message can never offer.

The logistics ontology and where its hierarchy actually breaks

The data model underneath all of this is not a schema in the database sense. IATA-Cargo states it directly: "The ONE Record data model is specified as an ontology which is also referred to as a semantic model", whose classes represent things rather than rows: "The ONE Record cargo ontology is organized as a set of data classes that represent real world concepts in transport and logistics, also referred to as digital twins." Those generic classes have a name of their own, "These generic data classes are referred to as Logistics Objects in the world of ONE Record", and the break with the previous generation of standards is stated in the same passage, with its own missing article intact: "This is transition from the traditional logistics and transport EDI systems that only exchanged messages and documents." (Portal, Data Model, Concepts)

The glossary defines the parent concept in plain terms: "A data object that represents a meaningful entity in the logistics business. These may represent documents like air waybills but may also be more granular such as company details or a transport segment description." (Portal, API Specification, Glossary) The cargo ontology's own root class comment matches it: "Logistics Object parent class, containing all common properties for logistics objects." (IATA-Cargo/ONE-Record, cargo ontology)

Read this way, seven named classes look like one flat family: LogisticsObject, LogisticsEvent, Shipment, Waybill, Piece, TransportMovement and Booking. The cargo ontology, read directly rather than summarized, says otherwise. Shipment and Waybill inherit straight from LogisticsObject. Piece sits one level lower, under an intermediate class the ontology comments as "Superclass: PhysicalLogisticObjects represent the digital twin of an object in the logistics supply chain that physically exist". TransportMovement sits under a scheduled-activity superclass and Booking under a service superclass, each its own intermediate step rather than a direct child of LogisticsObject. (IATA-Cargo/ONE-Record, cargo ontology)

LogisticsEvent is the class that breaks the flat-family reading outright. It declares no rdfs:subClassOf pointing at LogisticsObject. It is a separate class, linked to the objects it describes through a property named eventFor, and the specification's own API gives it a separate endpoint, /logistics-events, rather than folding it into the Logistics Object URI space. An integration that models status updates as just another Logistics Object, or expects one to answer the same GET a Waybill answers, is modeling against a hierarchy the specification does not have. Organizations carry the same URI discipline as the objects they hold data for: "Therefore, the same URI structure as for Logistics Objects MUST be applied." An organization's identifier "MUST uniquely identifies an organization in its data exchanges with other organizations that use ONE Record." (Portal, API Specification, Concepts)

JSON-LD is the serialization not an add-on

The portal fixes the default encoding without hedging: "The ONE Record API specification defines JSON for Linking Data (JSON-LD) as the default RDF serialization." That follows because "the ONE Record data model is based on a ONE Record cargo industry ontology using the Resource Description Framework (RDF) format." (Portal, API Specification, Concepts) A record is data described in RDF first, and JSON-LD is simply the shape it takes on the wire.

How many ontologies make up ONE Record depends on which source answers the question. The specification repository's own folder listing counts two: "ONE Record Data Model ontology and ONE Record API models ontology." (IATA-Cargo/ONE-Record, repository README) The Data Model Concepts page also counts two, but a different pair: "The ONE Record data model consists of two ontologies: the ONE Record cargo ontology and the ONE Record core code lists ontology". "The ONE Record core code lists ontology contains industry code lists as named individuals" and "The ONE Record cargo ontology contains industry concepts, their properties, and their relationships between them." (Portal, Data Model, Concepts) Put the two together and there are three named vocabularies, cargo, core code lists and API, at the namespaces https://onerecord.iata.org/ns/cargo, https://onerecord.iata.org/ns/coreCodeLists and https://onerecord.iata.org/ns/api. A class identifier reads https://onerecord.iata.org/ns/cargo#Piece, an identifier rather than a page; no page fetched for this article resolves at that host beyond a redirect stub.

JSON-LD's own job, per the W3C JSON-LD 1.1 Recommendation of 16 July 2020, is compression of vocabulary into short, developer-friendly names for identifiers. The keyword that carries that vocabulary is constrained: @context must not be given an alias, though the specification does allow it as a key inside a node object, a value object, a graph object, a list object, a set object, a nested property or an expanded term definition, and its value must be null, an IRI reference, a context definition or an array of those.

The other keyword ONE Record leans on constantly is the one that turns a link between two logistics objects into something a processor can dereference. Per the same recommendation, @id may be aliased and may serve as a key inside a node object or a graph object, and a node object holding nothing but that single @id property counts as a reference to a node object defined elsewhere in the document. That single mechanic, an object holding nothing but @id, is how a Waybill points at a Shipment hosted on a different server without embedding it. ONE Record depends on that mechanic; JSON-LD does not depend on ONE Record for anything.

The API surface from creation to audit trail

The interface itself is an HTTP contract between participants, allowing "all participants in the network to connect their IT systems to the IT systems of their partners, using state of the art web technologies." Each participant appears on the network as a node, and typically "a ONE Record node represents a single organization." A server "provides some or all of the specified ONE Record REST API endpoints and some or all of the data model specifications." (IATA-Cargo/ONE-Record, API README) Interoperability follows from the URI alone: "any compliant ONE Record client/server can connect and exchange data with any other ONE Record client/server by simply accessing each other's endpoints via URIs." (Portal, API Specification, Concepts) Identity is a URI issued once and never touched again: "This Logistics Object URI MUST NOT be changed as it is the permanent identifier of a specific Logistics Object." Generation itself is "left to each ONE Record API implementer as long as it complies with the valid Logistics Object URI." (Portal, API Specification, Concepts)

Reading is mandatory; creating is not, and that asymmetry is the single most misread point in the whole API. Every object "MUST be accessible via its Logistics Objects URI using the HTTP GET method." Meanwhile "only the holder of the logistics object MAY create a logistics object with any business logic or technology." A creation endpoint "should be restricted to internal usage only, and it must not be made available to external entities." (Portal, API Specification, Logistics Objects) A partner integration that assumes a public POST endpoint for creating objects is assuming a capability the specification never asks a server to offer.

Change is a request, not a write, once an object exists outside its holder. Updates go through HTTP PATCH, narrowed to "two actions only: delete and add." "The combination of delete and add is equivalent to replace." Changes are decided by the holder and applied as a single (atomic) event. (Portal, API Specification, Logistics Objects) Every accepted or rejected change lands in an AuditTrail of a Logistics Object, retrievable by users and maintained by the holder. (Portal, API Specification, Logistics Objects) A ledger of requests, not a version history of the object, is what a downstream consumer gets.

Subscriptions notifications and access delegation

Updates move over a publish and subscribe channel rather than a poll, through asynchronous communication via HTTP. (Portal, API Specification, Subscriptions) A subscription cannot be edited once it exists: "A Subscription MUST be immutable (unchangeable object), i.e. a Subscription cannot be changed after it is created and published." Updating one means revoking it and creating a new one. Delivery is the publisher's obligation: "The publisher of a Notification MUST ensure the guaranteed delivery." A message queue per subscriber and topic is recommended. (Portal, API Specification, Subscriptions) Every server must implement "a Notifications endpoint to receive data from ONE Record clients", fired when an object is created or updated. (Portal, API Specification, Notifications)

Access is granted, not assumed, and refused by default. Access control lists sit on the Logistics Object level, never on an individual property, and an operation nobody granted returns a "403 Forbidden HTTP error." (Portal, Security, Access Control) Four permissions cover retrieving an object, requesting a change to it, adding an event to it and retrieving an event's details, and single and public authorization are mandatory for every server while group authorization is only recommended. Only the holder may delegate: "Only the Holder of a Logistics Object MAY delegate access to logistics objects." The holder rules on every request. (Portal, API Specification, Access Delegations) The class diagram gives a delegation an optional expiry date alongside its permissions and objects, so a grant never revoked and never given an end date can quietly outlive the shipment it was created for, a failure mode the data model makes possible.

Cargo-XML coexistence and the migration path

IATA maintains a dedicated Data Orchestration section for exactly this problem, because nothing about the transition is automatic: "The transition from EDI to Data Sharing is highly dependent on the mapping between messages and ONE Record." Messaging itself is not new: "Messaging standards (Cargo IMP and then Cargo XML) have been used extensively for the past decades by the industry." The industry's reason for moving past it is scalability: "messages in their current form have shown to be limited in terms of scalability with regards to upcoming regulations such as ACI/PLACI regimes." The older of the two message families is already retired: "As CIMP standard has been sunset since 31st December 2014, we focus on CXML messages from CXML Toolkit 12th Edition." (Portal, Data Orchestration, Cargo-XML Mapping) Nothing on that page says CXML itself is being retired next; it says CIMP already was.

The mapping splits into two distinct problems, and conflating them is where a migration plan usually goes wrong. Some of it is a change of mindset rather than a field-for-field swap: "we need to consider a shift of mindset between EDI and Data sharing as well as a transition to Piece level tracking that ONE Record allows." The rest is mechanical, and two general rules govern it in both directions. Converting out of ONE Record loses precision on purpose: "the general rule is to truncate data to fit CXML length restrictions." Converting in drops what the model treats as redundant: "totals are usually not in ONE Record data model if all detailed data are already available." (Portal, Data Orchestration, Cargo-XML Mapping) IATA ties the mapping to CXML Toolkit Edition 12 against Data Model 3.3.0, the last ontology version the mapping page endorses.

The published mapping names eight CXML messages and gives each its own readiness note, which is the honest granularity a page-level source supports; a field-by-field crosswalk was never extracted in this run and none is claimed here. The table below states only what the mapping page itself states.

Concept	ONE Record construct	Cargo-XML equivalent (per the published mapping)	Migration failure mode
The master air waybill	Waybill, a subclass of LogisticsObject	XFWB 5.00, ready for production	Treating the waybill as the root record rather than one object among several linked objects
The house air waybill	Waybill with waybillType = House	XFZB 4.00, ready for production	Losing the link to the underlying Shipment and TransportMovement objects
Status and milestone updates	LogisticsEvent, posted through its own /logistics-events endpoint	XFSU 6.00, ready for production	Modelling an event as a property update on the shipment, which loses the append-only history
Piece-level detail	Piece, a subclass of PhysicalLogisticsObject	Not covered by the published mapping; the page calls piece-level tracking a shift of mindset rather than a message conversion	Collapsing individual pieces back into shipment totals, which the model deliberately avoids
Flight and transport legs	TransportMovement, a subclass of LogisticsActivity	XFFM 4.00, first draft needing review; XTMV 2.00, to be assessed	Relying on an unfinished mapping as though it were production ready
Booking	Booking, a subclass of LogisticsService	XFBL 3.00, ongoing	Same as flight and transport legs, an ongoing mapping treated as settled
Totals and summary values	Omitted by design once the detailed data already exists	Present in CXML as stored fields	Recreating totals as stored values instead of deriving them from piece-level detail
Field length and precision	No decimal or length limit imposed by the ontology itself	CXML length restrictions apply	Silent truncation on export, per the mapping page's own stated rule

Read as a set, the table's honest gap is the piece-level row. A mapping table that invented an XML equivalent for piece-level detail would be a stronger-looking table and a weaker fact; saying the published mapping has none tells an integration team exactly where to stop expecting a crosswalk and start designing one. The same coexistence questions surface outside air cargo, and our logistics software development guide covers the wider EDI-to-API transition across freight modes.

Where the specification disagrees with itself

A working draft is allowed to be unfinished, and an integration still needs a way to know which version it is building against. The API README carries its own version and status line, Draft, not yet approved by the COTB or the CSC, at 2.3.0-dev. The class diagram defining every request, subscription and access-delegation type in that same API states 2.4.0, also Draft. The API ontology's Turtle metadata declares a version IRI ending in 2.4.0-dev, last modified 12 August 2026, while the portal's own worked JSON-LD examples send a content type of application/ld+json; version=2.3.0. Four different version strings, across four artifacts of the same specification, none dated the same way. Strip the -dev suffix from two of them and it is two releases instead of four, 2.3.0 and 2.4.0, but the working draft states neither reduction itself. (IATA-Cargo/ONE-Record, API README, IATA-Cargo/ONE-Record, API class diagram, IATA-Cargo/ONE-Record, API ontology) The cargo ontology carries the same problem in a smaller form: a version IRI ending in 3.3, a comment opening with "Version 3.3 RC1", and the Cargo-XML mapping page's own "Data Model 3.3.0" as the version endorsed by the Cargo Operations and Technology Board, three spellings of the same release. (IATA-Cargo/ONE-Record, cargo ontology, Portal, Data Orchestration, Cargo-XML Mapping) The right integration behavior is to stop asking which number is current and attribute every version string to the exact file it came from.

An integration that trusts the repository README's folder listing will go looking for a data-model directory that is not there. The README lists it and describes what belongs inside, "ONE Record logical data model, ONE Record physical data model, Design Principles;" but that path returns a not-found response on the branch the README itself documents. The directory that actually exists in its place is named ontology. (IATA-Cargo/ONE-Record, repository README)

The clearest case of the specification disagreeing with itself sits inside the subscription mechanism covered earlier. The TopicType enumeration that tells a subscriber what a topic refers to is declared as LOGISTICS_OBJECT_TYPE and LOGISTICS_OBJECT_URI in the API class diagram on the repository's working branch. The same enumeration, embedded in the specification portal's own Subscriptions page, is declared as LOGISTICS_OBJECT_TYPE and LOGISTICS_OBJECT_IDENTIFIER, and the portal's own worked example sends the second spelling in a live request. Two documents from the same standard name the same value differently, and the one carrying a worked example is the one to follow until the repository and the portal agree with each other. (IATA-Cargo/ONE-Record, API class diagram, Portal, API Specification, Subscriptions) None of this is a reason to wait for a finished standard. It is a reason to pin a version per artifact and log which spelling a partner server actually accepts, checking a server's declared supported ontology and API versions, which its own ServerInformation class already carries as properties, before trusting a payload rather than after a payload fails to parse.

How Pharos Production helps

A ONE Record integration is a server that publishes what a carrier holds, a client that reads and subscribes to what partners publish, an authorization layer that turns a delegation into an enforced permission and a Cargo-XML bridge that knows exactly which messages are production ready and which are not. Getting the ontology's real hierarchy right, attributing every version string to its source file and building ACL and delegation logic against the specification's own class diagram rather than a summary of it are what decide whether the integration survives a second airline's server. Our aviation software development team scopes exactly that kind of build, alongside the wider set of airline, MRO, crew and dispatch systems covered in our aviation software development in 2026 guide.

Sources: IATA's ONE Record program page on iata.org; the IATA-Cargo ONE Record specification repository on GitHub, branch master (the repository README, the working-draft API README, the API class diagram, the cargo ontology and the API ontology, all in their raw form); the ONE Record specification portal at iata-cargo.github.io/ONE-Record/stable/ (API Specification Concepts, Logistics Objects, Subscriptions, Notifications, Access Delegations, Glossary, Security Access Control, Data Model Concepts and Cargo-XML Mapping); and the W3C JSON-LD 1.1 Recommendation of 16 July 2020. Read on 21 September 2026. Engineering guidance, not legal or regulatory advice.

FAQ

Last updated: September 21, 2026

Quick answers to common questions about custom software development, pricing, process and technology.

Expand all Collapse all

Search FAQs

Popular

Type to filter questions and answers. Use Topic to narrow the list.

Showing all 6

• ★ Featured question. Does ONE Record replace Cargo-XML immediately, or do they run side by side?

  Copy link Copies a direct link to this answer to your clipboard.

  Side by side, for as long as an integration needs them to. IATA's own Data Orchestration material states that the transition depends entirely on the mapping between the two, and it sunset the older CIMP messaging family in December 2014 while continuing to build the mapping against current Cargo-XML messages.

  Nothing in the published mapping states a retirement date for Cargo-XML itself, and this guide does not either. Our reading at Pharos Production is that a pragmatic integration runs a bridge: publish the ONE Record objects a partner asks for, keep the Cargo-XML messages a partner still expects and let each side migrate at its own pace rather than forcing a cutover neither system's partners are ready for.

• What happens if a partner's ONE Record server is unreachable when a subscriber needs an update?

  Copy link Copies a direct link to this answer to your clipboard.

  The specification puts that risk on the publisher, not on the network. Guaranteed delivery of a notification is stated as the publisher's obligation, and a per-subscriber, per-topic message queue is recommended precisely so a temporary outage does not lose an update.

  Our practice at Pharos Production is to treat a partner endpoint going down as an expected operating condition rather than an edge case: queue outbound notifications with retry and backoff, alert on a queue that is not draining and never assume a single failed delivery means a partner never received the change at all.

• Is a LogisticsEvent the same kind of thing as a Shipment or a Waybill?

  Copy link Copies a direct link to this answer to your clipboard.

  No, and the ontology is explicit about it once you read the class file rather than a summary of it. Shipment and Waybill both inherit directly from LogisticsObject.

  LogisticsEvent declares no such inheritance; it is linked to the object it describes through a separate property and served through its own endpoint. Treating an event as just another logistics object, or expecting it to answer the same request a Waybill answers, is building against a hierarchy the specification does not have, and it is one of the fastest ways a first ONE Record integration produces a working demo that fails against a second partner's server.

• Which API version should a new integration target?

  Copy link Copies a direct link to this answer to your clipboard.

  None of them exclusively, because the working draft itself carries four different version strings across four artifacts, two releases if the -dev suffix is stripped, from a README still marked draft and not yet approved by IATA's Cargo Operations and Technology Board to a class diagram and an ontology file that each state a different number again. Our practice at Pharos Production is to record which file a given version string came from, check what a partner server actually declares it supports before sending a request and revisit that record whenever the repository or the portal changes, rather than hard-coding a single current version anywhere in the integration.

• Who is allowed to create a Logistics Object, and who is allowed to read one?

  Copy link Copies a direct link to this answer to your clipboard.

  Reading is a right every authorized party has by rule; creating is a privilege the specification hands to the holder alone, by whatever internal means that holder chooses, provided the resulting object answers on a reachable URI. The specification is direct that a creation endpoint should stay internal and never be exposed to outside participants at all.

  That asymmetry surprises teams used to a REST API that exposes symmetric create and read endpoints for the same resource, and it is worth designing for from the first sprint rather than discovering it after a partner asks why they cannot POST a new Waybill to your server.

• Does an access delegation expire on its own once a shipment is delivered?

  Copy link Copies a direct link to this answer to your clipboard.

  Not unless the integration makes it. The class that represents a delegation carries an expiry date as an optional field alongside the permissions and the objects it covers, which means a grant with no expiry set simply persists after the shipment it was created for is closed out.

  Our practice at Pharos Production is to treat every delegation as carrying a lifecycle event of its own: set an expiry that matches the business transaction wherever the workflow allows it, and where it does not, run a periodic sweep that flags grants tied to shipments long since delivered so a stale permission is a finding, not a silent standing risk.

I work with startup founders who need a dedicated software development team but don’t want to gamble on hiring, random outsourcing, or opaque delivery.
Most founders face the same problem sooner or later.
Early technical and team decisions lock the product into tech debt, slow delivery, missed milestones and constant re-hiring. By the time this becomes visible, fixing it is already expensive.

As a CTO and software architect, I help founders design, build and run dedicated development teams that work as a true extension of the startup. Not as a black-box vendor.

My focus is on complex products where mistakes are costly:

• Web3 and blockchain platforms
• FinTech and regulated products
• High-load startup systems
• MVP → scale transitions

We don’t do body-shopping.
We don’t sell generic outsourcing.

Instead, we help founders:

• build the right team structure from day one
• keep technical ownership and transparency
• scale delivery without losing control
• avoid vendor lock-in and hidden risks

Teams are aligned with the product roadmap, business goals and long-term architecture. Not just short-term velocity.