Code Lists
ONE Record data model 3.0.0 introduced code lists for type safety. These replaced data properties holding enumerations and strings referencing a particular code list.
This page provides guidance on how to use code lists in practical use cases.
Note
Instances where code lists are used are indicated by (three stripes-Icon) in the ontology visualizer.
Code lists are built on using custom objects. Many code lists are published as named individuals in the ONE Record coreCodeLists ontology.
For unpublished or open code lists, the object CodeListElement is used. A code list is open when it is not restricted to standard values. It allows putting in a custom code.
Whenever a CodeListElement is referenced, it MUST feature a unique URI/@id such as https://mycodelist.org/handlingCodes#ABC. It MUST NOT be embedded. However, the URI does NOT need to be resolvable either.
The URI can point towards an existing ontology such as the code lists published as part of the UN/CEFACT Web Vocabulary.
If hosted as a Logistics Object, it SHOULD include the properties as indicated in the ontology in addition to a searchable, human-readable URI.
CodeListElement¶
The CodeListElement is a logistics object. It is the superclass of all other code lists in ONE Record.
As such, all codes defined as named individuals are viewed as instances of the CodeListElement.
It features the following properties if hosted as an Logistics Object:
| Property | Description |
|---|---|
| code | Code or short version of a code, for example "CH" for Switzerland when referring to the UN/LOCODE code list |
| codeDescription | Description or long version of the code, for example "Switzerland" for Switzerland when referring to the UN/LOCODE code list |
| codeLevel | Integer indicating the level of a code if a code list is hierarchical, for example HS-Codes |
| codeListName | Official name of the code list without version number when direct reference is not possible, for example "UN/LOCODE" when referring to the UN/LOCODE code list |
| codeListReference | URL to access the code list the code is taken from, for example "https://unece.org/trade/cefact/unlocode-code-list-country-and-territory" for UN/LOCODE. |
| codeListVersion | Version of the code list, for example "223-1" for UN/LOCODE. Used if the property codeListName is used or the version is not apparent from the resource referred to in property codeListReference. |
Note
When instanced as a Logistics Object, you MUST define a reusable and unique URI for the CodeListElement.
Note
The properties code and either codeListName or codeListReference at least SHOULD be used if instanced.
Recommended URI structure¶
To filter and search for codes, the URI SHOULD be understandable if parsed as a string. The URI does NOT need to be resolvable. It is RECOMMENDED to use the following structure:
As a practical example, an URI CAN look like this:
Alternatively, if hosted as logistics object:
Examples¶
Example 1: Enumeration¶
In the following example, a named individual defined in the cargo ontology is used to set the loadType of a Piece to LOOSE.
{
"@context": {
"cargo": "https://onerecord.iata.org/ns/cargo#"
},
"@type": "cargo:Piece",
"cargo:loadType": [
{
"@id": "cargo:LOOSE"
}
]
}
(examples-dm/code-lists-enumberation.json)
Example 2: Closed Code List¶
In the following example, a named individual defined in the coreCodeLists ontology is used to set the securityStatus of a SecurityDeclaration to NSC.
{
"@context": {
"cargo": "https://onerecord.iata.org/ns/cargo#",
"ccodes": "https://onerecord.iata.org/ns/coreCodeLists#"
},
"@type": "cargo:SecurityDeclaration",
"cargo:securityStatus": [
{
"@id": "ccodes:SecurityStatus_NSC"
}
]
}
Note
This code list is defined in the ONE Record coreCodeLists ontology.
(examples-dm/code-lists-closed-code-list.json)
Example 3: Open Code List, defined Code¶
In the following example, named individuals are used to set the specialHandlingCodes of a Piece as EAW and NSC.
{
"@context":{
"cargo":"https://onerecord.iata.org/ns/cargo#",
"ccodes":"https://onerecord.iata.org/ns/coreCodeLists#"
},
"@type":"cargo:Piece",
"cargo:specialHandlingCodes":[
{
"@id":"ccodes:SpecialHandlingCode_EAW"
},
{
"@id":"ccodes:SecurityStatus_NSC"
}
]
}
(examples-dm/code-lists-open-code-list-1.json)
Note
Both code lists are defined in the ONE Record coreCodeLists ontology. Note that a SecurityStatus is also an acceptable Special Handling Code.
Example 4: Open Code List, custom Code¶
In the following example, a named individual defined is used to set the specialHandlingCodes of a Piece as EAW. Additionally, CUS, a custom organization-specific special handling code, is used. The URI is resolvable like a normal Logistics Object.
{
"@context":{
"cargo":"https://onerecord.iata.org/ns/cargo#",
"ccodes":"https://onerecord.iata.org/ns/coreCodeLists#"
},
"@type":"cargo:Piece",
"cargo:specialHandlingCodes":[
{
"@id":"ccodes:SpecialHandlingCode_EAW"
},
{
"@id":"https://1r.example.com/logistics-objects/specialHandlingCodes#CUS"
}
]
}
(examples-dm/code-lists-open-code-list-2.json)
If resolved, the returned logistics object may look like this:
{
"@context": {
"cargo": "https://onerecord.iata.org/ns/cargo#",
"ccodes": "https://onerecord.iata.org/ns/coreCodeLists#"
},
"@id": "https://1r.example.com/logistics-objects/specialHandlingCodes#CUS",
"@type": "ccodes:SpecialHandlingCode",
"cargo:code": "CUS",
"cargo:codeDescription": "Custom Special Handling Code",
"cargo:codeListName": "Some Airline Custom Handling Codes",
"cargo:codeListVersion": "2024-04"
}
(examples-dm/code-lists-open-code-list-2-lo-example.json)
Note
The code instanced SHOULD be of type required by the property, in this case as SpecialHandlingCode for property specialHandlingCodes.
Example 5: CodeListElement, undefined Code List¶
In the following example, a new object of type CodeListElement is created as a LogisticsObject to transmit the hsCode of a Product.
{
"@context": {
"cargo": "https://onerecord.iata.org/ns/cargo#"
},
"@type": "cargo:Product",
"cargo:hsCode": [
{
"@id:": "https://1r.example.com/hsCodes#9023"
}
]
}
(examples-dm/code-lists-code-list-element.json)
Example 6: Code List defined in other Vocabulary¶
In the following example, a named individual defined in the UN/CEFACT Web Vocabulary is used to set the currencyUnit of a CurrencyValue describing the declaredValueForCarriage of a Waybill to CHF.
{
"@context": {
"cargo": "https://onerecord.iata.org/ns/cargo#",
"unece": "https://vocabulary.uncefact.org/"
},
"@type": "cargo:Waybill",
"cargo:waybillType": "cargo:MASTER",
"cargo:declaredValueForCarriage": [
{
"@type": "cargo:CurrencyValue",
"cargo:numericalValue": 5000.00,
"cargo:currencyUnit": [
{
"@id:": "unece:CurrencyCodeList#CHF"
}
]
}
]
}