Add URLs to official documentation

Posted by Robert Sanderson on 20/7/2021

Wholehearted agreement. Even if they're expressed in different ways by different representations of the conceptual model, if we can standardize the URI then an RDFS description and an OWL description of *the same URIs* can be used by different communities without breaking interoperability. If we get RDF*, or other declarative technological models for describing graph structures, then they too could describe the use of the URIs in their contexts.
 

Posted by Detlev Balzer on 20/7/2021

I'm one of those. 

The standard recipe would be to follow the linked data principles as explained e.g. in the http://linkeddatabook.com/ . While the technical specs may look a bit intimidating at first, turning an RDF graph plus documentation into fully compliant linked data source requires only modest technical skills and effort. 

All the required pieces for URL routing come with commonly used web servers, and converting RDF on-the-fly into any desired format is handled out of the box by open source RDF stores such as RDF4J or Fuseki. Any aspiring young web programmer out there to take on the challenge?

Posted by Thanasis on 20/7/2021

I agree with this. Shouldn't it be part of the RDF implementation document? 

Posted by George on 26/7/2021

Dear all,

Thanks for your feedback on this. So it sounds like there is interest in discussing this as an issue in the next SIG. 

The proposal that was in my mind was that the specification document (the word/pdf) would also have the URL/I as a hotlink in the documentation of the class or property and that if you clicked this it would bring you to the server which would guide you to the definition of the class in some structured format be that RDFS or OWL or the detailed documentation format on the website: http://www.cidoc-crm.org/Entity/E3-Condition-State/version-7.1.1 .

But there may be other perceptions or ideas around the best way of including this conveniently and where.

Posted by Nicola Carboni on 29/7/2021

Dear all,

Normally the link to the description already exists, but they only use property/classes number and they reflect CIDOC-CRM version 5.0.4

In fact, if you go to
http://www.cidoc-crm.org/cidoc-crm/P2
you should be able to see an html version of the property description relative to P2 has type.

I noticed in the website that at the moment we can also point to the xml version of the documentation (which also use only property/classes number for the link). For example:
http://cidoc-crm.org/versions/cidoc_crm_v7.1.1.xml#P2 points to the documentation of the property P2_has_type as described in version 7.1.1 of the documentation.

A simple solution would be to just redirect from the uri of a class/property to to the latest XML.
Example: http://www.cidoc-crm.org/cidoc-crm/P2_has_type should redirect to the property description in the last version available of the documentation (http://cidoc-crm.org/versions/cidoc_crm_v7.1.1.xml#P2). Redirect should also be established for the property only present in RDF (e.g. P81a/P81b)

However, that opens up the problem of versioning. CIDOC-CRM in respect to many other ontologies is quite dynamic, so definitions changes and classes are added (or deleted) in time. The very first problem that come to mind is relative to the classes which have been deleted (e.g. Retrieve the scope note of E38 not knowing that it was deleted in version 6.2.9). However, even for the classes which have simply changed scope note, should we redirect to one specific version of the ontology (therefore reflecting the definition of that class in a specific moment in time when it was used) or simply point to the current one?

Because in case of the former solution, the namespace uri should include the version of CIDOC-CRM..

In the 53rd CIDOC CRM & 46th FRBRoo SIG meeting, the SIG discussed the proposal by GB to add URLs to the official documentation. 

Arguments made in favor of the proposal: 

• a URI is an official name for the thing it describes, it shouldn’t change in principle –if it is placed in the specification document (not as a hotlink, but as a separate section in the definitions), then it would be easy to edit/delete them if they change
• URIs could be added to the supplementary files, not the specification document. If the URI policy changes, it would entail having to update just the supplementary material, NOT the entire specification document –but on the other hand, the rdfs serialization is where the URIs get published

Arguments made against it: 

• adding URIs to the specification document might not be such a good idea –they are part of a particular technological solution that is currently available. The standard need not point to that particular implementation. 
• having versionless URIs in the pdf versions of the specification document means that the thing they point to is to the “current” –i.e., last published –version (in all likelihood not the one that the .pdf stands for). No use to that. 
• historical versions of the specification document could have links to the URIs that were relevant at the time of their implementation. Maybe add a comment pointing to the current (updated) version of the implementation. 
   

Alternative proposal: 

it is possible to use versioned URIs for all versions of the standard, that redirect to the html page of that version. There are no implementation issues there (f.i., E59 Primitive Value is represented therein). Plus, add a statement that “this does not correspond to the latest version”.

Overall discussion: 

If case in point is to always get to the “current” version, then it might be better to generate a supplemental document listing all “current” URIs for E&P definitions than adding the URIs to the documentation. It all boils down to what the purpose of having the URI link in the document is: (a) link to the current version, or (b) some other functionality? 

• Re (a): having the URIs pointing to the official documentation from some particular web-application makes sense, but from the official documentation to the current version of the documentation online, not so much. 
• Since (b) is not very clear, we need a use case to make an informed decision about whether or not to introduce them. 
  • The overall case seems to be that when one is using different applications (that most likely run on different versions of the CRM) –it is good for version control and for tracking the history of changes implemented in the model. 
  • However, this has already been implemented in the .html version (with links to all versions and comments re the last time they were edited). 
    Accessed through: Resources/ (respective CIDOC CRM version)/Classes & Properties Translations & Versioning

Decision: Use case needed by the end of June to make an informed decision. Otherwise we close the issue. 
HW: GB [and anyone else interested]

May 2022