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.

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 embedded object CodeListElement is used. A code list is open when it is not restricted to standard values.

The approach also allows to refer codes defined as linked data outside of ONE Record. This includes, for example, code lists published as part of the UN/CEFACT Web Vocabulary .

This page provides guidance on how to use code lists in practical use cases.

CodeListElement

The CodeListElement is an embedded 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 a custom instance as embedded object is required:

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

The properties code and either codeListName or codeListReference at least SHOULD be used if instanced.

Examples

Example 1: Enumberation

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": "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": "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": "ccodes:SpecialHandlingCode_EAW",
    "cargo:specialHandlingCodes": "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, a new embedded object is created to set CUS, a custom organization-specific special handling code, using the properties of the CodeListElement.

{
    "@context": {
        "cargo": "https://onerecord.iata.org/ns/cargo#",
        "ccodes": "https://onerecord.iata.org/ns/coreCodeLists#"
    },
    "@type": "cargo:Piece",

    "cargo:specialHandlingCodes": "ccodes:SpecialHandlingCode_EAW",
    "cargo:specialHandlingCodes": [
        {
            "@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.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 embedded object of type CodeListElement is created to set the hsCode of a Product.

{
    "@context": {
        "cargo": "https://onerecord.iata.org/ns/cargo#"
    },
    "@type": "cargo:Product",

    "cargo:hsCode": [
        {
            "@type": "cargo:CodeListElement",            
            "cargo:code": "9023",
            "cargo:codeDescription": "Instruments, apparatus, models",
            "cargo:codeLevel": 4,
            "cargo:codeListName": "Harmonized System",
            "cargo:codeListVersion": "Nomenclature 2024"
        }
    ]
}

(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": "unece:CurrencyCodeList#CHF"
        }
    ]
}

(examples-dm/code-lists-other-linked-data-code-list.json)