Better document output format / RDF data model

[philbarker]

Currently I can only find the RDF data model that underpins the output format in an issue here.

• [ ] It should be more readily findable & better documented.
• [ ] As it is an RDF model serialized in JSON-LD for export, we should have stable URIs and a vocabulary definition file for the terms in the desm: namespace.

[edgarf]

@philbarker does it require any engineering work here, or would we cover both items with documentation/configuration enhancements?

[philbarker]

@edgarf Assuming the current output matches the model there shouldn't be any work required on your point—I say that as an assumption because since the current documentation is not great there is always a chance of errors.

[philbarker]

there are inconsistencies between the model diagram, the term definitions and what is in the actual output:

• the model diagram uses rdfs:domain and rdfs:range, which are not suitable to the semantics of multiple classes in domain/range; the output uses desm:domainIncludes and desm:rangeIncludes, which aren't defined in the term definitions. There is a term definition for desm:range that would do for rangeIncldues but nothing for domain.

  • [x] change model diagram to desm: properties as in output
  • [ ] add desm:domainIncludes desm:rangeIncludes to term definition file, remove desm:range.

• the model diagram uses desm:Class for domain and range of properties, which is odd. desm:Class is not defined in term definition file but is used for the range of desm:range.

  • [x] change model diagram to use rdfs:Class
  • [ ] change term definitions to use rdfs:Class

• the model diagram has an attribute of desm:Schema called desm:abstractClass which is not in the term definition file, and maybe should be a relationship pointing to a skos:Concept? It is not used in the mapping output.

  • [x] change model diagram to show desm:abstractClass arrow from desm:Schema to skos:Concept
  • [ ] add to term definition file.

• the model diagram has some text that should be dct:descrption & dct:title

  • [x] add these to diagram in place of garbled text

(Changes here are intended to clarify the current model, not deal with other issues such as better modelling of mappers and organizations or adding transformation info to term mappings.)

[edgarf]

@philbarker, now as we have merged the PR, can we move this task into column "Merged" or are there some unfinished items?

[philbarker]

There is still more to do.