Checking out to deal with ontology documentation via LODE

[riccardoAlbertoni]

I have experimented a little with Widoco [1]. Widoco produces LODO-compliant documentation. Besides a tool to generate ontology documentation, it also means to deploy a web base application to deploy the documentation as HTTP reachable pages.

We focus on the generation of the ontology documentation as a first step and then we will check if the web-based publication is needed for our purposes or if we can simply publish the ontology documentation attached in the git repository.

Installing Widoco

• Clone the git rep [1] on local directory
• Built the maven package https://github.com/dgarijo/Widoco?tab=readme-ov-file#building-the-jar-executable
• Being sure to be in the WIDOCO directory, we can exec the app in the JAR, for example, by typing in the prompt java -jar ./JAR/widoco-1.4.21-jar-with-dependencies.jar -uniteSections -rewriteAll -ignoreIndividuals -noPlaceHolderText -oops -outFolder ..\CTP_Ontology\documentation -ontFile ..\CTP_Ontology\CTP_Ontology_core.ttl [OLD - java -jar ./JAR/widoco-1.4.21-jar-with-dependencies.jar -uniteSections -includeImportedOntologies -rewriteAll -ignoreIndividuals -oops -outFolder ..\CTP_Ontology\documentation -ontFile ..\CTP_Ontology\CTP_Ontology_cloning.ttl]
• a new directory CTPdocumentation is created. The web documentation can be visualized opening indexing-en.html in that directory with a browser.

A complete list of the widoco option are available at https://github.com/dgarijo/Widoco/?tab=readme-ov-file#options

Suggestions

• Check https://w3id.org/widoco/bestPractices, which provides best practices about what kinds of metadata should be included. We need to include, title, author and description.
• Metadata elements to consider are listed in https://github.com/dgarijo/Widoco/blob/master/doc/metadataGuide/guide.md
• Check if we can publish the documentation in Git as explained in https://www.youtube.com/watch?v=OkMrAroKtjI

[1] https://github.com/dgarijo/Widoco

[riccardoAlbertoni]

Issues:

• [x] I coudn't manage the order of authors, Tiziana needs to be the first name.
• [x] I opted for cc-by license, but this is a decision we need to consider together
• [x] We need to mention the Funder, especially the doctoral funders.
• [x] Instances of examples should not included
• [x] Abstract and diagrams might need to be included
• [x] We need to decide on a base URI for the ontology - ( we decided for https://w3id.org/ctp )
• [x] doublecheck the OOPS validations created when adding -oops to widoco command
• [x] In documentation insert CQs

[TizianaPasciuto]

The previously listed points have been addressed; however, some of them require additional notes:

• [x] I opted for cc-by license, but this is a decision we need to consider together

Added to the repository an .md file with the specific license document.

• [x] Abstract and diagrams might need to be included

The ontology model image has been inserted, but since the repository is not public, the image is not displayed on the HTML page. I tested it with images published on the web, and they are displayed without any issues. I think that the problem will be solved once the ontology is made public.

• [x] We need to decide on a base URI for the ontology - ( we decided for https://w3id.org/ctp)

It was necessary to change the namespace from https:///w3id.org/ctp to https:///w3id.org/ctp#, because without the presence of the # the ctp prefix was always displayed.

• [x] doublecheck the OOPS validations created when adding -oops to widoco command

Resolution of the 69 missing annotations reported by OOPS! (P08. Missing annotation), since for classes and properties of the ontology it was always missing rdfs:label. As a result, the problem found on the html page related to the classes displayed with the lowercase letter instead of the uppercase letter was also solved. Partial resolution of the 16 cases detected by OOPS! (P11. Missing domain or range in properties). Only one case concerned the CTP ontology, due to an oversight that has been corrected. The other missed domain or range in properties concern ontologies that have been referred to as equivalent to some properties of CTP ontology.

• [x] In documentation insert CQs

I added in the repository an .md file that contains the 25 CQs in both Italian and English and I have attempted to write them for querying in SPARQL. They need to be checked as I may have made mistakes. Furthermore, while writing them, I realized that in some cases, inverse relationships might be necessary, which I had not considered in the ontology model.

In addition to that, the README file of the ontology has been compiled. It now includes a brief introduction and information about the methodology followed for development, as well as some key phases of the development process. It also indicates any tools used and provides links to resources that contributed to the creation of the ontology (such as CQs, tabular information, model diagram, etc.). A references section will also be added.

The work has brought to light new issues, including:

• [ ] The inability to modify certain sections of the HTML page from the reference .ttl file, namely:
  • [ ] Insertion of the Tables of content --> consulting the LODE documentation, it appears that it should "generate itself," but in this case, it is not happening;
  • [x] Management of 1.Introduction, 2. Overview ..., 4. Cross-reference ..., 5. References, 6. Acknowledgments.
• [x] Management of equivalences between classes and properties;
• [x] Management of class headers, especially when referring not only to classes from the CTP Ontology but also to other ones (e.g., foaf, owl time, etc.).

[TizianaPasciuto]

New steps (emerged during the today's meeting - 21.03.2024):

• [x] Creation of the CTP core ontology, without classes&properties equivalent to other ontologies;
• [x] Definition of inverse relations, to be inserted in the CTP core ontology;
• [x] Adjusting instantiations;
• [x] Create a new .ttl file containing ontology equivalences;
• [x] Resolution of OOPS! issues;
• [x] Testing the CQs in YASGUI.

[TizianaPasciuto]

The previously listed points have been addressed; however, some of them require additional notes:

• [ ] Testing of the SPARQL Query tab in Protege for the CTP core ontology;

As already verified during the meeting on March 21st, the SPARQL query tab doesn't work. The plugins suggested by various websites were not found in the update list because they were already present in my version of Protege.

• [x] Resolution of OOPS! issues;

There are still two points left to resolve. I also read the related publication (now uploaded in Zotero - DOI:10.4018/ijswis.2014040102), but it doesn't provide much additional information on resolving my issues. These points are:

• P22. Using different naming conventions in the ontology --> I also consulted the relevant guide recommended on OOPS! (now uploaded in Zotero - Ontology Development 101: A Guide to Creating Your First Ontology), however, despite fixing some points that could have been in conflict (for example, there were uppercase letters that should have been lowercase), I am still unable to resolve this issue. Among other things, it does not indicate where there are inconsistencies, making it difficult to find them.
• P30. Equivalent classes not explicitly declared --> OOPS! considers "Theme" and "Subject" as equivalent classes, but they are not. I also tried to indicate them as disjoint in the ontology (an edit that was later removed), but the result on OOPS! remains unchanged.