traceability-vocab

traceability-vocab copied to clipboard

I had 2 chats with @onthebreeze re governance and editorial procedures for binding to Linked Data (which basically means adding to the JSONLD context). As part of that, I looked at BillOfLading.

Get https://w3c-ccg.github.io/traceability-vocab/contexts/traceability-v1.jsonld and search for BillOfLading. Here are the problems that I see:

• Cannot use individual (codelist member) as a property:

billOfLadingNumber: {@id: "https://vocabulary.uncefact.org/ReferenceCodeList#BM"},
bookingNumber: {@id: "https://vocabulary.uncefact.org/ReferenceCodeList#BN"},
portOfLoading: {@id: "https://vocabulary.uncefact.org/LocationFunctionCodeList#9"},
portOfDischarge: {@id: "https://vocabulary.uncefact.org/LocationFunctionCodeList#11"},

• -> Could use this pattern:

<billOfLading1> identifier <billOfLading1/id/billOfLadingNumber>, <billOfLading1/id/bookingNumber>.
<billOfLading1/id/billOfLadingNumber> a Identifier;
   type <https://vocabulary.uncefact.org/ReferenceCodeList#BM">, value "lading123".
<billOfLading1/id/bookingNumber> a Identifier;
   type <https://vocabulary.uncefact.org/ReferenceCodeList#BN">, value "booking456".

• -> Or could define custom props, and declare them exactMatch to the UNCEFACT individuals:

tr:billOfLadingNumber a owl:DatatypeProperty;
  rdfs:label "Bill of lading number";
  skos:exactMatch <https://vocabulary.uncefact.org/ReferenceCodeList#BM>.
tr:bookingNumbera owl:DatatypeProperty;
  rdfs:label "Booking number";
  skos:exactMatch <https://vocabulary.uncefact.org/ReferenceCodeList#BN>.

• Unclear whether that's a URL of a party, or party name. (It's clear from the JSON schema, but not the JSONLD context). Declare @type:@id for avoidance of doubt:

carrier: {@id: "https://vocabulary.uncefact.org/carrierParty"},
consignor: {@id: "https://vocabulary.uncefact.org/consignorParty"},
consignee: {@id: "https://vocabulary.uncefact.org/consigneeParty"},
notify: {@id: "https://vocabulary.uncefact.org/notifiedParty"},
freightForwarder: {@id: "https://vocabulary.uncefact.org/freightForwarderParty"},

• -> Another big problem I see is that the JSON schema repeats the structure of a party 6 times (eg search for "email"), i.e. is not modular
• -> Another problem is that the JSON schema demands each party to be an embedded object. What if I want to share data from a big KG of companies?
• Similarly, here it's better to declare @type:@id. And particulars is unspecific, better to use consignmentItem or consignmentItems (because it's an array)

particulars: {@id: "https://vocabulary.uncefact.org/includedConsignmentItem"}

• Cannot use class as property; and schema:Purchase does not exist; and these bindings make no sense, at least to me

relatedDocuments: {@id: "https://schema.org/Purchase"},
freight: {@id: "https://schema.org/ParcelDelivery"},

---

Relating to #948, who can make appropriate mappings? How can we educate people to do it?

According to git blame, BillOfLading, @nissimsan made the first problematic mapping described above (9 months ago):

• was https://service.unece.org/trade/uncefact/vocabulary/uncl1153/#Bill_of_lading_number (also an individual, i.e. wrong)
• changed to https://vocabulary.uncefact.org/ReferenceCodeList#BM

And I think that @OR13 looked at it.

Classes to classes, and Props to props. Only constant stuff to Individuals

The structure of this BOL schema is an artifact of building JSON-LD from JSON schema... I think we've learned enough from this experiment to confirm, it's not a good approach.

It's better to hand craft each JSON-LD context and each json schema, and make sure both the json and RDF representations are as good as they can be.

That's a lot more work, and it's likely work that many won't have the skills to do, many verifiers might only care about one or ther other, but I believe it's the better approach.

According to git blame, BillOfLading, @nissimsan made the first problematic mapping described above (9 months ago):

was https://service.unece.org/trade/uncefact/vocabulary/uncl1153/#Bill_of_lading_number (also an individual, i.e. wrong) changed to https://vocabulary.uncefact.org/ReferenceCodeList#BM

I updated all the CEFACT references as that vocab got promoted from draft to final. Apparently already wrong to begin with. I was never happy to reference a code list to begin with. The problem I was facing was I could find any actual definition for, say, bill of lading number. CEFACT should define them, but don't. This came closest.

I would suggest removing these bad cases and let the Trace define them instead. I would support such a PR.

Closing, while this would be a better solution in the long term, it would require a significant overhaul that no one is willing to undertake.