Vocabulary granularity / architecture

[onthebreeze]

There is another question that we need to resolve before we can finalise the JSON-LD NDR - which is the question of vocabulary architecture / granularity.

• is it all one huge vocabulary including all code lists? Even if the unece data models and code lists were published in one huge file, there is still the problem of vocabularies from other authorities (eg ISO, WCO, WTO, etc).
• I think the answer lies in the granularity of the vocabulary governance - we cant go coarser than that. So, for example, there is a totally separate group that manages and releases the UN/LOCODE list - see https://www.unece.org/cefact/locode/service/location.html. it's a very bog list - just look at the list for one country (australia) https://service.unece.org/trade/locode/au.htm. so it seems to me that un/locodes are their own vocabulary and API.
• Buy ship pay RDM is managed as one thing but it's quite big and could be usefully decomposed into domains like "trade", "transport", "regulatory", and "core" as shown in the reference model diagram on https://edi3.org/semantic-specs/
• back to code lists, some are really just a local value range of a property in the RDM like TransitDirection and so are not separately governed and can probably just be part of the domain vocabulary. Others properties like VesselRegistrationCounty will have values defined by the totally separate ISO country code list.

So, my suggestion is that

• Data Model vocabularies by published at the @context granularity of a business domain like "transport".
• local code lists like the allowed values for transitDirection are just part of the same vocabulary @context.
• separately managed code lists like country code, UOM, locode, etc have their own @context and vocabulary graph

agree?

[Fak3]

There are few separate things of concern to create a vocabulary:

• Vocabulary
  • machine readable representation commonly expressed in json-ld and turtle, served at some url
  • human-readable (html) representation, served in single or multiple html pages
• Namespace of vocabulary terms ( ususlly base http url like http://edi3.org/vocab/v1# )
• Json-ld context in the form of json, served at some url

It is recommended that dereferencing any term from the vocabualry by its full namespaced url with web-browser will result or redirect to a page containing human-readable description of that term. Also recommended that dereferencing the full term url with http header "accept: application/json+ld" results or redirects to the machine-readable rdf representation of the vocabulary.

So if we have several business domains like "transport", "trade", etc - we should decide:

• Should machine-readable representations of those domain vocabularies be served at the same url, or separate?
• How should human-readable vocabulary documentation be organized? Single html page and url? One page per domain? One page per term?
• Should each business domain have its own http namespace, or share single one?
• Should we create separate json-ld context files for each domain, or they can share single one?

[Fak3]

BSP RDM currently lists these business-process domains: 'Agricultural', 'Buy-Ship-Pay', 'Cataloguing', "Context Categories Mandatory for BIE's", 'Cross Industry', 'Cross Industry Trade', 'Cross-Border', 'Customer to bank payment initiation', 'FLUX', 'In All Contexts', 'Invoicing', 'Laboratory Observation', 'MSDS Reporting', 'Pricing', 'Project Management', 'Remittance', 'Scheduling', 'Supply Chain', 'Traceability', 'Trade', 'Transport', 'e-Certificate of Origin'