Code Lists
The ONE Record data model version 3.0.0 introduced code lists to enhance type safety. This update replaces the use of generic enumerations and strings that previously referenced specific code lists, ensuring more structured data properties.
This page offers practical guidance on applying code lists effectively in real-world scenarios.
Note
Code lists are visually marked by a triple-stripe icon in the ontology visualizer.
Code lists are implemented using custom objects, with many predefined as named individuals within the ONE Record coreCodeLists ontology.
For code lists that are not predefined or are open-ended, the CodeListElement object is used. A code list is considered "open" when it allows custom entries rather than restricting input to a fixed set of values.
Whenever a CodeListElement is referenced, it MUST have a unique URI/@id following the structure defined below. This URI MUST NOT be embedded but does not need to be directly accessible.
This URI can reference an existing ontology, such as code lists published by the UN/CEFACT Web Vocabulary.
Note
Code lists element cannot be hosted as Logistics Objects. A new code list element definition MUST be accessible with its human-readable URI. The code list element MUST specify the properties defined in the CodeListElement object. For internal use, a unique URI in the format {{baseURL}}/{{codeListName}}#{{code}} is sufficient.
CodeListElement¶
The CodeListElement is a custom object specifically defined for code lists. 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:
| 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 creating a CodeListElement instance, it is essential to assign a reusable and unique URI.
Note
The properties code and either codeListName or codeListReference at least SHOULD be used if instanced.
URI structure¶
For effective filtering and searching, the URI SHOULD be readable when parsed as a string and does need to be resolvable for retrieving additional information. The URI MUST follow the following structure:
As a practical example, an URI can look like this:
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 example below, a named individual is used to assign the specialHandlingCodes property of a Piece to EAW. Additionally, a custom code, "CUS," is introduced as an organization-specific special handling code.
For custom codes, the URI MUST be resolvable. The organization that manages the custom code may publish it within an ontology that extends the specialHandlingCodes section of the ONE Record coreCodeLists ontology. Alternatively, the organization can publish detailed information about the code directly at the defined URI without using an ontology.
{
"@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/specialHandlingCodes#CUS"
}
]
}
(examples-dm/code-lists-open-code-list-2.json)
If resolved, the URI should all information regarding the custom code as any code define in the ONE Record coreCodeLists ontology (i.e.:EAW). An alternative approach is to return the CodeListElement in JSON format, as demonstrated in the example below:
{
"@context": {
"cargo": "https://onerecord.iata.org/ns/cargo#",
"ccodes": "https://onerecord.iata.org/ns/coreCodeLists#"
},
"@id": "https://1r.example.com/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"
}
Note
It is recommended to follow the CodeListElement structure. However, the holder of the element can decide its own structure as far as all the information from the CodeListElement object are present. Only the structure of the IRI is mandatory and MUST follow the guidelines from the URI Structure section (#)
(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 example below, a new object of type CodeListElement is hosted at https://1r.example.com/ to convey the hsCode for 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"
}
]
}
]
}