Define the term "Transport Document"

[nissimsan]

I personally like that you embrace the term Transport Document, which I assume covers BOLs and SWBs. I would suggest you explain this in the description. “Transport document” is very generic and could mean many other things too (especially if you are not a techie working for a carrier).

[raisoman]

@nissimsan well it is in the Glossary of terms:

"The document that governs the terms of carriage between shipper and carrierfor maritime transportation. 2 distinct types of transport documents exist:

• Bill of Lading
• Sea Waybill"

To avoid duplication, that is the only place we should keep it. Now we just need a unique'ish place to put a link to the glossary, suggestions are welcome.

[nissimsan]

Not advocating for duplication, but there's a different definition on the openapi. PR'ed an update suggestion.

If you really want to avoid duplication, then don't keep the Glossary in a PDF. :)

[rlilov]

I was reading the TnT specification and came upon Transport Document qualifier. Was a bit confused what it means.
What is the reasoning not to call it Bill of Lading, like it is known in the industry?

Sea Waybill is a type of bill of lading, as well as House BL, to order BL, straight BL etc.. and cannot really understand the logic of above classification.

[nissimsan]

Hi @rlilov,

We are in semantic nitpicking territory here. But no, technically a Waybill is not a type of BL. While they carry many of the same data elements and are substitutionally used, each is a legal type of transport document in their own right.

Introducing a term which isn't commonly used in shipping jargon should certainly be done with care. Data modeling-wise, though, a generic class for two similar sub-classes is good practice.

[rlilov]

Hi @nissimsan,

My motivation for this post was that from a position of a potential API consumer, I am expecting terminology that matches my prior knowledge and widely accepted terms, that facilitate easy comprehension of the parameters and payload, but as you say, it is probably nitpicking.

Still, would be nice when researching new API, to see familiar concepts without having to consult external dictionaries, by the same token, it took me some time to realize that equipment reference is container number.

[nissimsan]

Ah yes... Transport Equipment is UNCEFACT lingo.

I completely agree with your sentiment. The true solution to the conundrum you are describing is JSON LD, which segregates common industry slang from concise, standardized semantical purity. You might be interested in this article on the topic.