versioning of vocabularies and code lists

[onthebreeze]

We also need to document a strategy to handle versioning.

The current UN/CEFACt process is to release updates roughly every 6 months - as a re-release of the entire dictionary. for example

• https://www.unece.org/cefact/codesfortrade/unccl/ccl_index.html - for the core component library
• https://www.unece.org/tradewelcome/un-centre-for-trade-facilitation-and-e-business-uncefact/outputs/standards/unedifact/directories/2011-present.html - for the EDIFACT libraries
• https://www.unece.org/cefact/locode/welcome.html - here you see that code lists tend to be over-written with the latest rather than maintained as a history.

In general there is very little assistance to indicate what has changed - it is up to the user to compare current and previous dictionaries to see what has changed. On the positive side, in the vast majority of cases, the dictionary updates are additions and not changes to existing dictionary terms - so generally non-breaking.

for JSON-LD vocabularies we will obviously not be re-publishing the entire vocabulary each time! But we should expect a reasonable number of new properties and codes to appear each 6 months and a smaller number of new classes.

What I might suggest when a new RDM/CodeList is released is:

• compare against previous release to categorise all changes as
  • new (common)
  • updated (rare)
  • deprecated (rare)
• manually examine updates to assess whether they are breaking
  • a breaking change is something like a significant change in the business meaning of a term. I expect this to be very rare, maybe never. But if it does happen then blacklist this item and raise a governance request to fix it.
  • a non-breaking change is is something like a minor change in the text of the definition that doesnt change it's meaning.
• add some more cefactElementMetadata properties such as
  • "edi3:currentStatus"
  • "edi3:createdDate"
  • "edi3:lastModifiedDate"
  • "edi3:deprecatedDate"
• update the published vocabulary with :
  • new properties and classes inserted
  • updated (non breaking) properties and classes over-written
  • deprecated properties and classes marked as such
• and maybe add a master "edi3:lastvocabularyReleaseDate" and "edi3:currentVocabularyVersion" (semver) at the root of the published vocabulary.

Allowed statuses could be

• draft - it's a proposal, use at your risk (maybe in a separate namespace?)
• active - it's stable, use it confidently
• deprecated - it's still supported but new builds should not use it
• obsolete - not supported and dont use it. (these would be removed from the vocabulary and maintained in a separate history namespace or something)

something like this?

{
  "@id": "edi3:consignor",
  "rdfs:type": "rdfs:Property",
  "rdfs:domain": "edi3:Consignment",
  "rdfs:range": "edi3:Party",
  "edi3:cefactElementMetadata": [
    {
      "@id": "cefact:UN01011054",
      "@type": "edi3:AssociationBIE", 
      "edi3:cefactDictEntryName": "Referenced_ Supply Chain_ Consignment. Consignor. Trade_ Party",
      "edi3:cefactBusinessProcess": "Buy-Ship-Pay",
      "edi3:currentStatus":"active",
      "edi3:createdDate": "21-03-2020"
    },
    {
      "@id": "cefact:UN01004212",
      "@type": "edi3:AssociationBIE", 
      "edi3:cefactDictEntryName": "Supply Chain_ Consignment. Consignor. Trade_ Party",
      "edi3:cefactBusinessProcess": "Buy-Ship-Pay"
      "edi3:currentStatus":"deprecated",
      "edi3:createdDate": "01-04-2017"
      "edi3:deprecatedDate": "21-03-2020"
    },
  ]
}

separately governed major code lists like UN/LOCODE Code lists would be similar - status and date at the code item level and master release level

[Fak3]

Json-ld context will also be updated every 6 moths. I think the context url should include vocab version in it. Something like https://edi3.org/vocab/2020.06/context.json So when a data consumer receives the data with unknown context url at the top, it should fetch that new context and cache forever. But this has to be done carefully, as an adversary could try to force a data receiver cache to grow by sending him flood of forged data packets. I am still uncertain of the optimal policy to prevent this.