Maintain & offer OTM5-endpoints for code lists

[BobZuidhoek]

I'd like to add something to the OTM 5 spec.

What would you like to add or change to the specification? Please be as clear and concise as possible.

Within Transport Orders (and its relating context such as Goods, Location, etc.) a handful of code lists are used to populate fields. I would like to see that OTM maintains these code lists in a central place and offers API's to download (sync) the code list to local systems (e.g. TMS, ERP).

The desired way is that we position the code lists as advisory code lists (to promote standardization).

A couple of code lists come to mind...

A code list for list for tertiary & secondary packaging
This would be the code list for the PackagingMaterial / EquipmentType / EquipmentSubtype attribute in Goods.

This is the code list for things like pallets, trolleys, crates, carton, box, etc. They can be one-way packaging, but also RTI (Returnable/Reusable Transport Items). If this is not standardized and we would, for example, want to communicate a 120x80 Euro pallet, different codings like "EPAL", "Europallet", "EPAL120x80", "Euro", etc pass by. It makes sense that a OTM-standardized list is kept for this. This ensures proper and quick mapping of messages from and to internal company systems.

The challenge with this particular code list is that several code lists exist, that all complement each other.

• UN/EDIFACT/CEFACT code list 7065
• GS1 Benelux emballagecodes https://www.gs1.nl/sectorafspraken-over-standaarden/productdata-levensmiddelen-drogisterij-agf-en-foodservice/gs1-5-5
• Floricode (i.e. this is the GS1 organization for horticulture industry) Emballage code list.
• Some other if you start Googling.

So for this list, OTM should take a leading role in maintaining the content of the code list.

Other code lists should be maintained & downloadable via API for completeness and ensuring standardization

• List of IncoTerms
• List of 2-code countries (based on ISO-3166)
• Currencies (based on ISO 4217)
• Unit of measure types (cm, kg, etc.) maybe based on code list 6411 as used in EDI
• DocumentTypes (Photo, CMR, Commercial invoice, Customs Invoice, etc.). I don't know if some standardized list already exists.

Describe alternatives you've considered
None. Particularly packaging codes are hard to standardize if not not centrally maintained.

[bmeesters]

Hello Bob,

We have talked about using more standardized code lists in OTM before and as far as I can tell everyone is in favor. The problem however is indeed the one you describe, there are already quite a few and they seem to be partly overlapping and partly complementary.

Up until now we did not have time to start digging into this too much ourselves, which is why the code lists did not make it in yet. Our focus has been mostly about enabling parties to express their use cases and extend OTM where necessary. I am sure it will make it in eventually, but if you want it quickly you can take a leading role and start assembling the ones you need. Otherwise I am not sure how soon this will land.

edit There already was some work done that I overlooked. We are checking how much work we still need to do.

[bmeesters]

@woutvandenheuvel did some preliminary work together with Menno Lambooy looking at available code lists.

OTM5 currently supports (part of) the GS1 transport role parties and GS1 transport modes

Wout and Menno propose (if I understood correctly):

• Add the GS1 package types or package and container types (not sure which one to use)
• CBS commodity codes

On top of that I think the suggestions of Bob are good:

• add the ISO country codes
• The list of currencies
• units of measure

Regarding document types I am also not sure whether one exists, but we could maintain one ourselves for now.

[BobZuidhoek]

Note about the CBS commodity codes:

• The CBS codes are based on the TARIC nomenclature (this is the EU-wide Customs Goods Classification). TARIC is mostly 8-digit long, but can be longer codes (see https://en.wikipedia.org/wiki/TARIC_code). CBS gets the data from the single source of truth of the EU here: https://ec.europa.eu/taxation_customs/business/calculation-customs-duties/customs-tariff/eu-customs-tariff-taric_en
• Harmonized system codes are set worlwide by the World Customs organization (see https://en.wikipedia.org/wiki/Harmonized_System). These are always up til 6 digits long.

Customs organizations (countries or trade zones) further specify HS-code system into more specific parts (as EU does with TARIC). Some countries or trade zones make no further specification other than the HS-code itself.

Note that technically 'numbers' in these nomenclature can begin with leading 0's (which truly are part of the number). Therefore, these fields are essentially alfanumerical.

[bmeesters]

This issue is partly resolved. We have included the ISO standard for country codes, currencies, GS1 standard for package material and more thoroughly documented the use of other types measure units. There is still room for improvement but those are better tracked in separate smaller tickets.