REferencing Actual code enumerations from the Code lists class in JSON-LD vocabulary

[onthebreeze]

From slack thread Andreas Pelekies:

And can you help me with the current implementation of JSON-LD and Code lists, please? In the vocab the code lists are defined as separated classes without a content. And the properties using the codes are referencing them exactly as defined:

{
            "@id": "uncefact:UNCL2013Code",
            "@type": "rdfs:Class",
            "rdfs:comment": "Code specifying the rate of recurrence.",
            "rdfs:label": "Frequency code"
}

But there is no link to the code list definition itself. For example, the file uncl2013.jsonld contains

"@context": {
    "uncefact": "https://service.unece.org/trade/uncefact/vocabulary/uncefact#",
    "uncl2013": "https://service.unece.org/trade/uncefact/vocabulary/uncl2013#",
    "rdf": "http://www.w3.org/1999/02/22-rdf-syntax-ns#",
    "rdfs": "http://www.w3.org/2000/01/rdf-schema#"
  },
  "@graph": [
    {
      "@id": "uncl2013:Annually_(calendar_year)",
      "@type": "uncefact:UNCL2013Code",
      "rdfs:comment": "Code defining a yearly forecast.",
      "rdf:value": "A"
    }

So, it defines uncl2013 (not UNCL2013Code) with the correct URI. But coming from the vocab it is not discoverable. Is this a bug or intended? Or can anyone help me with this how a developer will find out this automatically?

[onthebreeze]

@Fak3 and @kshychko

Any comments on this one?

[Fak3]

We can add a link from the uncefact:UNCL2013Code class definition to the url, where its instances (actual codes) are declared - https://service.unece.org/trade/uncefact/vocabulary/uncl2013/ i.e:

{
  "@id": "uncefact:UNCL2013Code",
  "@type": "rdfs:Class",
  "rdfs:comment": [
     "Code specifying the rate of recurrence.",
     "See https://service.unece.org/trade/uncefact/vocabulary/uncl2013/ for a list of available codes"  // ADDED
  ],
  "rdfs:label": "Frequency code",
  "rdfs:seeAlso": "https://service.unece.org/trade/uncefact/vocabulary/uncl2013/"   // ADDED
}

Would that improve discoverability enough?

[onthebreeze]

It would certainly enhance discoverability, yes. But is rdfs:seeAlso the right predicate to say "this is the value domain of this property?"

[Fak3]

There is no better predicate that I am aware of.

One thing we can do is to move the UNCL2013Code class definition from uncefact: to uncl2013: namespace, where its instances are declared. This way you will be forced to retrieve the list of all instances along with class definition.

In this case our StarUML plugin should be adapted to separate class from instances on import.

[AP-G]

I'd prefer the latter solution. We should not make it dependent on any tool, not StarUML nor GEFEG or any other. The definition is intended for users without any knowledge of UN/CEFACT or tool-specialities. So, an intuitive usage and discoverability should be the real focus as defined by the REST design principles.

[Fak3]

Related to #35