XFWB Mapping
XFWB purpose¶
XFWB message, and its predecessor FWB Message based on CIMP standard, is used to transmit complete Air Waybill data in accordance with IATA Cargo Services Conference Manual Resolution 600a. In reality we see multiple usage of the (X)FWB message that derive a bit from its original purpose. It can be the transmission of additional information (OCI for instance) or the update of goods description and weight/dimensions by a GHA. This page will focus on the main usage.
XFWB Mapping¶
Proposed mechanism¶
XFWB data fields are mostly a mix of Waybill, WaybillLineItem, Shipment, Pieces and TransportMovement data in ONE Record realm.
Handling of goodsDescription¶
In traditional cargo messaging (e.g. FWB/XFWB), goods description is expressed at the shipment level through one or more NC/NG lines (FWB) or <ram:NatureIdentificationTransportCargo> groupings (XFWB), representing the nature of the commodity for the entire consignment. ONE Record, by contrast, is designed around a piece-centric data model, where each Piece object can carry its own goodsDescription, enabling a finer-grained and more accurate representation of heterogeneous shipments.
ONE Record usage¶
In ONE Record, Piece#goodsDescription should be the primary field to populate. It is then up to the relevant stakeholder — most likely the Freight Forwarder — to decide whether Shipment#goodsDescription is additionally needed to provide a consolidated summary across all pieces. The two levels serve distinct purposes:
Shipment#goodsDescriptionsignals that the description is common to the entire shipment (all pieces/parts). It should only be used when a single description accurately applies to every piece in the consignment.- When a shipment contains multiple commodities, piece level should be preferred. Associated product descriptions and HS Codes for each commodity can also be provided at the piece level, offering richer classification granularity.
FWB (CIMP) → ONE Record¶
When converting a CIMP FWB message to ONE Record, if multiple NC/NG lines are present, they should be aggregated in Shipment#goodsDescription. There is no need to propagate this information down to the piece level — the shipment-level field is sufficient in this direction. The NG/NC line context should be taken into account during the mapping process to preserve the original structure and intent of the goods description lines.
XFWB → ONE Record¶
The <ram:NatureIdentificationTransportCargo> grouping in XFWB is less restrictive than the NC/NG lines in CIMP, allowing for richer free-text description. However, like its CIMP counterpart, it is scoped to the shipment level only. Multiple occurrences of this grouping should therefore be mapped to Shipment#goodsDescription, following the same logic as for CIMP FWB.
ONE Record → FWB/XFWB¶
When converting from ONE Record to either a FWB or an XFWB message, the following logic applies:
- If
Shipment#goodsDescriptionis populated, it should be mapped directly to the NC lines (FWB) or<ram:NatureIdentificationTransportCargo>groupings (XFWB). - If
Shipment#goodsDescriptionis absent, thePiece#goodsDescriptionvalues across all pieces shall be aggregated and mapped accordingly.
Usage of WaybillLineItem object¶
The WaybillLineItem object was introduced to properly share rate data as required in the Air Waybill. The WaybillLineItem has a n-to-1 relationship with a Waybill object and represents the different line items on the paper waybill with all their specifities based on the type of rating used. In order to stick to reality as much as possible, some data at line item level are taken from Pieces and LoadingUnits directly (dimensions, volume, ...). The WaybillLineItem object itself shall only contain rate specific data.
It is important to note that the WaybillLineItem has been added only in the context of sharing Air Waybill data. When looking at Operations, digital twins shall be used (Piece, Item, Product, etc.)
Origin Currency¶
CSC Resolution 600a indicates that rate charges are always expressed in the Origin Currency. This implies that we do not need a data property for the Origin Currency on the Waybil object. We refer to the currency defined in WaybillLineItem#rateCharge.
TransportMovement information¶
XFWB movement and routing details are mapped to TransportMovement objects. The proper linkage, starting from the Waybill is to to go through the Booking object which refers to the contractual engagements between a carrier and the freight forwarder. The various TransportMovement(s) planned for the transportation of the goods need to be linked to the Booking as an ActivitySequence.
Usage of OtherCharge object¶
The OtherCharge object is used to record all charges, it refers to <ram:ApplicableLogisticsAllowanceCharge> grouping in XFWB message. Code List 1.2 "Other Charge Code" is used to properly identify the charges associated with the Prepaid/Collect indicator.
Totals are not directly recorded in ONE Record as they can be directly calculated based on the existing data (e.g. filtering by type of charge and prepaid/collect indicator).
Other specific mapping guidelines¶
-
DensityGroupCodefield will be linked to Distribution phase as the feedback received from the industry shows that it's not an operational data but used for the Sales & Booking process part. It is then found on theBookingShipmentobject if required. -
Special Service RequestandOther Shipping Instructionscode fields are not in ONE Record as there is no evidence of an actual referential and standard used for those. Moreover it seems stakeholders use SSR or OSI for the same purposes. Thus we have merged intotextualHandlingInstructionsproperty in ONE Record. -
In the
ApplicableRatinggrouping, theTypeCodefield is set to F (Facial) by default as it is the only value used with CXML. -
In the
ApplicalbeFreightRateServiceChargegrouping, theAppliedAmountis not directly mapped as it is a total that needs to be derived from either the Rate or the multiplication of Rate and Chargeable weight depending on the type of charge. Refer to CSC Resolution 600a for further explanations.
Waybill parties¶
Various parties are identified in a XFWB message. There are some discrepancies with older CIMP specifications as well as with CSC Resolution 600a. It is essential to note that the CSC Resolution 600a contains the applicable requirements and terminology to follow.
- ConsignorParty: It is mapped to
partyRole = SHP - ConsigneeParty: It is mapped to
partyRole = CNE - FreightForwarderParty: It is mapped to
partyRole = AGT- Note that the Freight Forwader terminology was introduced with CXML essentially because the Agent is usually the Freight Forwarder. However both CIMP and Resolution 600a use Agent and we will use the same terminology in ONE Record.
Mapping of Security Declaration (eCSD) information¶
In legacy messaging standards the Security Declaration information is shared via the OCI segment. While it remains valid the SecurityDeclaration object has been specifically designed in ONE Record to contain all eCSD information. It is recommended to use the SecurityDeclaration to provide eCSD information with ONE Record, it implies that in the mapping process the OCI eCSD part should be mapped to SecurityDeclaration object.
For more details on eCSD mapping, please refer to the dedicated page on Data Model section.
CIMP Mapping example¶
Simple scenario¶
A simple scenario has been chosen to display the JSON-LD equivalent of a FWB subset. The example showcases: - A FWB with 6 pieces, total weight 120kg, chargeable weight 180kg (rate percentage of 1.5), total volume 0.31 cubic meter. - 4 Pieces have 80/40/20 dimensions - 2 Pieces have 60/30/15 dimensions - 2 HS codes are defined: 123456 and 987543 - Special handling code NSC (Not Screened) is used
The FWB extracts looks the following:
FWB/17
020-12345675BRULAX/T6K120.0MC0.31
...
RTD/1/P6/K120.0/CQ/W120.0/R1.50/T180.00
/2/NG/ELECTRICALS
/3/NG/NOT RESTRICTED
/4/ND/K80.0/CMT80-40-20/4
/5/ND/K40.0/CMT60-30-15/2
/6/NV/MC0.31
/7/NH/123456
/8/NH/987543
...
SPH/NSC
The JSON-LD equivalent looks the following:
{
"@context": {
"cargo": "https://onerecord.iata.org/ns/cargo#"
},
"@graph": [
{
"@id": "https://example.org/Waybill",
"@type": "cargo:Waybill",
"cargo:waybillLineItems": {
"@type": "cargo:WaybillLineItem",
"cargo:chargeableWeight": {
"@type": "cargo:Value",
"cargo:numericalValue": 120,
"cargo:unit": {
"@id": "https://vocabulary.uncefact.org/UnitMeasureCode#KGM"
}
},
"cargo:rateGrossWeight": {
"@type": "cargo:Value",
"cargo:numericalValue": 120,
"cargo:unit": {
"@id": "https://vocabulary.uncefact.org/UnitMeasureCode#KGM"
}
},
"cargo:rateClassCode": {
"@id": "https://onerecord.iata.org/ns/code-lists/RateClassCode#Q"
},
"cargo:ratePercentage":{
"@type": "cargo:Value",
"cargo:numericalValue": 1.5,
"cargo:unit": {
"@id": "https://vocabulary.uncefact.org/UnitMeasureCode#P1"
}
},
"cargo:rateVolume": {
"@type": "Value",
"numericalValue": 0.31,
"cargo:unit": {
"@id": "https://vocabulary.uncefact.org/UnitMeasureCode#MTQ"
}
}
},
"cargo:lineItemPackages": [
{
"@type": "cargo:LineItemPackage",
"cargo:packageWeight": {
"@type": "cargo:Value",
"cargo:numericalValue": 80,
"cargo:unit": {
"@id": "https://vocabulary.uncefact.org/UnitMeasureCode#KGM"
}
},
"cargo:pieceReferences": [
{
"@id": "https://example.org/Piece-1",
"@type": "cargo:Piece",
"cargo:skeletonIndicator": true,
"cargo:goodsDescription": "ELECTRICALS NOT RESTRICTED",
"cargo:specialHandlingCodes": {
"@id": "https://onerecord.iata.org/ns/code-lists/SpecialHandlingCode#NSC"
},
"cargo:dimensions": {
"@type": "cargo:Dimensions",
"cargo:height": {
"@type": "Value",
"numericalValue": 80,
"cargo:unit": {
"@id": "https://vocabulary.uncefact.org/UnitMeasureCode#CMT"
}
},
"length": {
"@type": "Value",
"numericalValue": 40,
"cargo:unit": {
"@id": "https://vocabulary.uncefact.org/UnitMeasureCode#CMT"
}
},
"cargo:width": {
"@type": "Value",
"cargo:numericalValue": 20,
"cargo:unit": {
"@id": "https://vocabulary.uncefact.org/UnitMeasureCode#CMT"
}
}
},
"cargo:contentProducts": [
{
"@id": "https://example.org/Product-1"
},
{
"@id": "https://example.org/Product-2"
}
]
},
{
"@id": "https://example.org/Piece-2",
"@type": "cargo:Piece",
"cargo:skeletonIndicator": true,
"cargo:goodsDescription": "ELECTRICALS NOT RESTRICTED",
"cargo:specialHandlingCodes": {
"@id": "https://onerecord.iata.org/ns/code-lists/SpecialHandlingCode#NSC"
},
"cargo:dimensions": {
"@type": "cargo:Dimensions",
"cargo:height": {
"@type": "Value",
"numericalValue": 80,
"cargo:unit": {
"@id": "https://vocabulary.uncefact.org/UnitMeasureCode#CMT"
}
},
"length": {
"@type": "Value",
"numericalValue": 40,
"cargo:unit": {
"@id": "https://vocabulary.uncefact.org/UnitMeasureCode#CMT"
}
},
"cargo:width": {
"@type": "Value",
"cargo:numericalValue": 20,
"cargo:unit": {
"@id": "https://vocabulary.uncefact.org/UnitMeasureCode#CMT"
}
}
},
"cargo:contentProducts": [
{
"@id": "https://example.org/Product-1"
},
{
"@id": "https://example.org/Product-2"
}
]
},
{
"@id": "https://example.org/Piece-3",
"@type": "cargo:Piece",
"cargo:skeletonIndicator": true,
"cargo:goodsDescription": "ELECTRICALS NOT RESTRICTED",
"cargo:specialHandlingCodes": {
"@id": "https://onerecord.iata.org/ns/code-lists/SpecialHandlingCode#NSC"
},
"cargo:dimensions": {
"@type": "cargo:Dimensions",
"cargo:height": {
"@type": "Value",
"numericalValue": 80,
"cargo:unit": {
"@id": "https://vocabulary.uncefact.org/UnitMeasureCode#CMT"
}
},
"length": {
"@type": "Value",
"numericalValue": 40,
"cargo:unit": {
"@id": "https://vocabulary.uncefact.org/UnitMeasureCode#CMT"
}
},
"cargo:width": {
"@type": "Value",
"cargo:numericalValue": 20,
"cargo:unit": {
"@id": "https://vocabulary.uncefact.org/UnitMeasureCode#CMT"
}
}
},
"cargo:contentProducts": [
{
"@id": "https://example.org/Product-1"
},
{
"@id": "https://example.org/Product-2"
}
]
},
{
"@id": "https://example.org/Piece-4",
"@type": "cargo:Piece",
"cargo:skeletonIndicator": true,
"cargo:goodsDescription": "ELECTRICALS NOT RESTRICTED",
"cargo:specialHandlingCodes": {
"@id": "https://onerecord.iata.org/ns/code-lists/SpecialHandlingCode#NSC"
},
"cargo:dimensions": {
"@type": "cargo:Dimensions",
"cargo:height": {
"@type": "Value",
"numericalValue": 80,
"cargo:unit": {
"@id": "https://vocabulary.uncefact.org/UnitMeasureCode#CMT"
}
},
"length": {
"@type": "Value",
"numericalValue": 40,
"cargo:unit": {
"@id": "https://vocabulary.uncefact.org/UnitMeasureCode#CMT"
}
},
"cargo:width": {
"@type": "Value",
"cargo:numericalValue": 20,
"cargo:unit": {
"@id": "https://vocabulary.uncefact.org/UnitMeasureCode#CMT"
}
}
},
"cargo:contentProducts": [
{
"@id": "https://example.org/Product-1"
},
{
"@id": "https://example.org/Product-2"
}
]
}
]
},
{
"@type": "cargo:LineItemPackage",
"cargo:packageWeight": {
"@type": "cargo:Value",
"cargo:numericalValue": 40,
"cargo:unit": {
"@id": "https://vocabulary.uncefact.org/UnitMeasureCode#KGM"
}
},
"cargo:pieceReferences": [
{
"@id": "https://example.org/Piece-5",
"@type": "cargo:Piece",
"cargo:skeletonIndicator": true,
"cargo:goodsDescription": "ELECTRICALS NOT RESTRICTED",
"cargo:specialHandlingCodes": {
"@id": "https://onerecord.iata.org/ns/code-lists/SpecialHandlingCode#NSC"
},
"cargo:dimensions": {
"@type": "cargo:Dimensions",
"cargo:height": {
"@type": "Value",
"numericalValue": 60,
"cargo:unit": {
"@id": "https://vocabulary.uncefact.org/UnitMeasureCode#CMT"
}
},
"length": {
"@type": "Value",
"numericalValue": 30,
"cargo:unit": {
"@id": "https://vocabulary.uncefact.org/UnitMeasureCode#CMT"
}
},
"cargo:width": {
"@type": "Value",
"cargo:numericalValue": 15,
"cargo:unit": {
"@id": "https://vocabulary.uncefact.org/UnitMeasureCode#CMT"
}
}
},
"cargo:contentProducts": [
{
"@id": "https://example.org/Product-1"
},
{
"@id": "https://example.org/Product-2"
}
]
},
{
"@id": "https://example.org/Piece-6",
"@type": "cargo:Piece",
"cargo:skeletonIndicator": true,
"cargo:goodsDescription": "ELECTRICALS NOT RESTRICTED",
"cargo:specialHandlingCodes": {
"@id": "https://onerecord.iata.org/ns/code-lists/SpecialHandlingCode#NSC"
},
"cargo:dimensions": {
"@type": "cargo:Dimensions",
"cargo:height": {
"@type": "Value",
"numericalValue": 60,
"cargo:unit": {
"@id": "https://vocabulary.uncefact.org/UnitMeasureCode#CMT"
}
},
"length": {
"@type": "Value",
"numericalValue": 30,
"cargo:unit": {
"@id": "https://vocabulary.uncefact.org/UnitMeasureCode#CMT"
}
},
"cargo:width": {
"@type": "Value",
"cargo:numericalValue": 15,
"cargo:unit": {
"@id": "https://vocabulary.uncefact.org/UnitMeasureCode#CMT"
}
}
},
"cargo:contentProducts": [
{
"@id": "https://example.org/Product-1"
},
{
"@id": "https://example.org/Product-2"
}
]
}
]
}
]
},
"cargo:shipment": {
"@id": "https://example.org/Shipment",
"@type": "cargo:shipment",
"cargo:pieces": [
{
"@id": "https://example.org/Piece-1"
},
{
"@id": "https://example.org/Piece-2"
},
{
"@id": "https://example.org/Piece-3"
},
{
"@id": "https://example.org/Piece-4"
},
{
"@id": "https://example.org/Piece-5"
},
{
"@id": "https://example.org/Piece-6"
}
]
}
},
{
"@id": "https://example.org/Product-1",
"@type": "cargo:Product",
"cargo:hsCode": {
"@id": "https://example.org/ns/HSCode#123456"
}
},
{
"@id": "https://example.org/Product-2",
"@type": "cargo:Product",
"cargo:hsCode": {
"@id": "https://example.org/ns/HSCode#987543"
}
}
]
}