The JSON Parses, but the Cargo Object Splits: Is IATA ONE Record Ready for Integration?
Use one cargo-object URI to test identity continuity across air-cargo partners before treating valid JSON as a successful IATA ONE Record integration.
Signals to watch
- Two partners exchange valid JSON-LD but do not preserve the same permanent Logistics Object URI
- An event, piece or booking reference resolves to a second object after a specific handoff
- A pilot acceptance review or production cutover has a named partner, owner and date
Two air-cargo partners can exchange JSON that parses perfectly and still create two identities for the same operational object. An IATA ONE Record integration is ready for serious review when the pilot can show where one permanent Logistics Object URI stops surviving a partner handoff, which event or reference forks, and who owns the dated acceptance test. “Both sides support JSON” is not that test.
An air-cargo integration sales engineer sees this in authorized airline, freight-forwarder, ground-handler and cargo-software Telegram groups. The target Signal is not a ONE Record announcement. It is an identity break tied to a partner and a pilot decision. Arriving a day late can miss the acceptance review; treating every API error as a project can waste engineering time on an expired token or a mismatched test dataset.
Consider this illustrative postmortem, not a real shipment or customer result:
“Carrier GET works now. Our piece update also returns 200, but their event shows under another shipment.”
“Could be old ontology? Demo is Tuesday.”
The JSON parses and the HTTP status is successful. Still unknown are the Logistics Object URI, object holder, shipment and piece relationships, ontology and API versions, authorization scope, event creator, legacy identifiers, environment and whether both parties used the same test cargo.
The parser passed; the cargo graph did not
IATA describes ONE Record as an air-cargo data-sharing standard built on a common data model and standardized secured web APIs (application programming interfaces). It is decentralized: data remains at the source and its owner controls access. The stable specification uses JSON-LD, or JavaScript Object Notation for Linked Data, to represent objects and their relationships.
That last word matters. A normal JSON parser checks syntax. It does not prove that Shipment, Piece, Booking and event references identify the same resources across two systems. ONE Record’s concept documentation requires every Logistics Object to have a globally unique, permanent URI. A URI is the network identifier used to address that object; it is not merely a local row number displayed as text.
If Partner A exposes a shipment at one URI and Partner B imports its visible fields into a newly minted local shipment URI without retaining the original link, both payloads can be valid while the shared cargo graph splits.
Reconstruct one failed handoff
Choose one object, not an entire flight. Record:
- the original Logistics Object URI and the holder that serves it;
- the endpoint, method, request time and authorization subject;
- the response body and linked object URIs;
- the receiving system’s stored URI and legacy identifiers; and
- the first event created after the handoff.
Now follow the references. Does the piece still point to the intended shipment? Does the event identify the same piece URI, or only repeat an air waybill number in a string field? Does a booking link resolve, and is the caller allowed to read it?
The first divergent URI is the useful defect boundary. A screenshot of matching air waybill text is weaker evidence because one number can be copied into several unrelated objects.
Break one: an object was flattened into text
Suppose the forwarder receives a Piece whose relationship points to a Shipment URI. Its legacy mapper stores only the air waybill number. When it later publishes an event, it creates a local shipment object from that number and links the event there.
The carrier now sees two shipment resources with similar business labels. Nothing was malformed. The receiving implementation discarded the identity-bearing relationship and later reconstructed an object it did not own.
The repair test is specific: retain the source URI, keep the legacy identifier as an identifier rather than a substitute identity, and create the next event against the original addressable object. If local persistence rules prevent that, the pilot has identified genuine integration work rather than a JSON-format problem.
Break two: an event points to the wrong level
A cargo event may describe a state change for a shipment, a piece or another Logistics Object. If the originating system records a piece-level scan but publishes the event against the shipment, the message can be readable yet operationally ambiguous.
Compare the event’s subject URI, event code, timestamp, location, creator and linked object. Then inspect the source scan record. An event timestamp alone is not enough: two pieces can pass the same location within seconds.
The acceptance question is plain: when the recipient opens the event subject, does it resolve to the object that actually changed? If not, the teams need a relationship and mapping fix. They do not yet need a broader platform replacement.
Break three: authentication succeeds while versions disagree
Security success and semantic compatibility are separate. A valid token can authorize a caller to retrieve a resource whose ontology terms the caller maps incorrectly. Conversely, compatible models do not overcome missing authorization.
Record the version of each component instead of saying “we use ONE Record 3.2.” IATA’s stable release notes list the components endorsed on 28 July 2025 as Ontology 3.2.0, API 2.2.0 and Data Orchestration 1.1.0. A partner can align on the API while using a mapping built for an older ontology.
Run the same object through authorization and semantic tests separately:
- Can the intended subject retrieve or update the exact URI under the agreed policy?
- Does each partner interpret the object type, properties and links with the agreed ontology?
- After the update, does the next event still resolve to the same object identity?
A 401 or 403 response points first to identity and access policy. A 200 response followed by a forked URI points to object handling. Mixing the two diagnoses produces a vague “ONE Record issue” that nobody can own.
What the 2026 target means
IATA promoted 1 January 2026 as an industry adoption target. It was not a government compliance date, a ban on Cargo-XML or proof that every airline, forwarder and handler had completed implementation. A group post saying “deadline passed” therefore establishes no project by itself.
The commercial question is the partner boundary: which objects and events must work, under which component versions, before which pilot or cutover decision? One carrier’s production API does not prove another party’s account, data policy or implementation readiness.
For other cargo-record ownership problems, compare how an ICS2 rejection is routed. For a broader deployment qualification pattern, see the IoT eSIM integration test. When a ranked Signal seems urgent, the confidence-scoring article explains why evidence still outranks a score.
TOP Prospect can connect incomplete fragments from groups the user deliberately connects and may access, preserve the original text, source and time, remove clear duplicates and explain review priority. It cannot authenticate to a cargo API, merge partner identities, validate ontology conformance, contact a group member or decide that a pilot has passed. The product route is described on the Signal intelligence page.
End the workshop with one acceptance condition: after Partner B consumes and updates Partner A’s object, the original permanent URI remains addressable, every new event points to the intended object, and both partners can reproduce that result under the agreed authorization and component versions. If that sentence fails, the first failed assertion is the next engineering task.
Frequently asked questions
Is IATA ONE Record a central cargo database?
No. IATA describes a decentralized data-sharing approach: data remains at its source, and the data owner controls access through standardized secured web APIs.
Does valid JSON prove ONE Record interoperability?
No. ONE Record uses JSON-LD, but syntactic parsing does not prove that partners use compatible ontology terms, preserve permanent object URIs, authorize the same resources or keep events linked to the intended objects.
What versions were endorsed on 28 July 2025?
The IATA release material lists ONE Record Ontology 3.2.0, API 2.2.0 and Data Orchestration 1.1.0 as endorsed components. They are separate versioned components, not one product called ONE Record 3.2.0.
Was 1 January 2026 a government compliance deadline?
No. IATA presented 1 January 2026 as an industry adoption target. It should not be described as a statutory deadline or proof that every airline completed adoption.
Sources and further reading
How a Signal worth attention is found
See how Top Prospect finds and organizes Signals worth checking, keeps the original Telegram context, removes duplicates, and helps you decide what to review first. You decide whether to follow up and what to do next.
