D2

Author: tabeatietz

.github/workflows/docs.yml

@@ -16,7 +16,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout main
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Deploy docs
         uses: mhausenblas/mkdocs-deploy-gh-pages@master

.github/workflows/qc.yml

@@ -19,12 +19,12 @@ jobs:
   ontology_qc:
     # The type of runner that the job will run on
     runs-on: ubuntu-latest
-    container: obolibrary/odkfull:v1.5.4
+    container: obolibrary/odkfull:v1.6
 
     # Steps represent a sequence of tasks that will be executed as part of the job
     steps:
       # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: Run ontology QC checks
         env:

.gitignore

@@ -1,9 +1,77 @@
+# ODK-managed rules, do not modify
+# If you need to add your own ignore rules, you may do so below
+# the "End ODK-managed rules" marker at the end of this file.
+.DS_Store
+semantic.cache
+bin/
+
+*.tmp
+*.tmp.obo
+*.tmp.owl
+*.tmp.json
+*-relation-graph.tsv.gz
+.template.db
+
+.github/token.txt
+
+/cto.owl
+/cto.obo
+/cto.json
+/cto.db
+/cto-base.*
+/cto-basic.*
+/cto-full.*
+/cto-simple.*
+/cto-simple-non-classified.*
+/mappings/
+/patterns/
+/reports/
+/subsets/
+
+src/ontology/mirror
+src/ontology/mirror/*
+src/ontology/reports/*
+!src/ontology/reports/release-diff.md
+src/ontology/cto.owl
+src/ontology/cto.obo
+src/ontology/cto.json
+src/ontology/cto.db
+src/ontology/cto-base.*
+src/ontology/cto-basic.*
+src/ontology/cto-full.*
+src/ontology/cto-simple.*
+src/ontology/cto-simple-non-classified.*
+
+src/ontology/seed.txt
+src/ontology/dosdp-tools.log
+src/ontology/ed_definitions_merged.owl
+src/ontology/ontologyterms.txt
+src/ontology/simple_seed.txt
+src/ontology/patterns
+src/ontology/merged-cto-edit.owl
+src/ontology/cto-edit.properties
+
+src/ontology/target/
+src/ontology/tmp/*
+!src/ontology/tmp/.gitkeep
+!src/ontology/tmp/README.md
+
+src/ontology/run.sh.conf
+src/ontology/run.sh.env
+
+src/ontology/imports/*_terms_combined.txt
+
+src/patterns/data/**/*.ofn
+src/patterns/data/**/*.txt
+src/patterns/pattern_owl_seed.txt
+src/patterns/all_pattern_terms.txt
+
+# End of ODK-managed rules
 widoco.jar
 src/.DS_Store
 /src/ontology/mirror
 /src/ontology/reports
 /src/ontology/tmp
-src/ontology/cto.owl
 src/ontology/cto-full.owl
 src/ontology/imports/.DS_Store
 src/metadata/cto.md

Dockerfile

@@ -8,6 +8,10 @@ RUN java -jar widoco-1.4.25-jar-with-dependencies_JDK-11.jar -ontFile /data/onto
 
 FROM ghcr.io/epoz/shmarql:latest
 
+# MkDocs D2 plugin 
+RUN wget -qO- https://d2lang.com/install.sh | sh -s -- && d2 version
+RUN pip install --no-cache-dir mkdocs-d2-plugin
+
 COPY docs /src/docs
 COPY mkdocs.yml a.yml
 RUN python -m shmarql docs_build -f a.yml
@@ -16,3 +20,4 @@ RUN mkdir /src/site/ontology
 COPY --from=widoco /public/doc /src/site/ontology
 RUN ls -l /src/site/ontology
 RUN cp /src/site/ontology/index-en.html /src/site/ontology/index.html
+

docs/domain-examples.md

@@ -85,4 +85,10 @@ stateDiagram
   class C1
   state "xF" as keysig_xF 
 
+```
+
+```d2
+
+x -> x 
+
 ```

docs/odk-workflows/ManageAutomatedTest.md

@@ -0,0 +1,28 @@
+## Constraint violation checks
+
+We can define custom checks using [SPARQL](https://www.w3.org/TR/rdf-sparql-query/). SPARQL queries define bad modelling patterns (missing labels, misspelt URIs, and many more) in the ontology. If these queries return any results, then the build will fail. Custom checks are designed to be run as part of GitHub Actions Continuous Integration testing, but they can also run locally.
+
+### Steps to add a constraint violation check:
+
+1. Add the SPARQL query in `src/sparql`. The name of the file should end with `-violation.sparql`. Please give a name that helps to understand which violation the query wants to check.
+2. Add the name of the new file to odk configuration file `src/ontology/uberon-odk.yaml`:
+    1. Include the name of the file (without the `-violation.sparql` part) to the list inside the key `custom_sparql_checks` that is inside `robot_report` key.
+    1. If the `robot_report` or `custom_sparql_checks` keys are not available, please add this code block to the end of the file.
+
+        ``` yaml
+          robot_report:
+            release_reports: False
+            fail_on: ERROR
+            use_labels: False
+            custom_profile: True
+            report_on:
+              - edit
+            custom_sparql_checks:
+              - name-of-the-file-check
+        ```
+3. Update the repository so your new SPARQL check will be included in the QC.
+
+```shell
+sh run.sh make update_repo
+```
+

docs/odk-workflows/ManageDocumentation.md

@@ -43,5 +43,3 @@ The documentation is _not_ automatically updated from the Markdown, and needs to
 3. Just to double check, you can now navigate to your documentation pages (usually https://ISE-FIZKarlsruhe.github.io/nfdi4culture/). 
    Just make sure you give GitHub 2-5 minutes to build the pages!
 
-
-

docs/odk-workflows/RepositoryFileStructure.md

@@ -19,12 +19,10 @@ These are the current imports in CTO
 | nfdicore | https://raw.githubusercontent.com/ISE-FIZKarlsruhe/nfdicore/main/nfdicore.ttl | mirror |
 | schema | https://raw.githubusercontent.com/schemaorg/schemaorg/refs/tags/v28.1-release/data/releases/28.1/schemaorg.owl | custom |
 | skos | http://www.w3.org/TR/skos-reference/skos.rdf | slme |
-
 ## Components
 Components, in contrast to imports, are considered full members of the ontology. This means that any axiom in a component is also included in the ontology base - which means it is considered _native_ to the ontology. While this sounds complicated, consider this: conceptually, no component should be part of more than one ontology. If that seems to be the case, we are most likely talking about an import. Components are often not needed for ontologies, but there are some use cases:
 
 1. There is an automated process that generates and re-generates a part of the ontology
 2. A part of the ontology is managed in ROBOT templates
 3. The expressivity of the component is higher than the format of the edit file. For example, people still choose to manage their ontology in OBO format (they should not) missing out on a lot of owl features. They may choose to manage logic that is beyond OBO in a specific OWL component.
 
-

docs/odk-workflows/components.md

@@ -14,35 +14,46 @@ components:
     - filename: your-component-name.owl
 ```
 
-3) Add the component to your catalog file (src/ontology/catalog-v001.xml)
+3) Refresh your repo by running `sh run update_repo`. This will automatically (1) create a new file in `src/ontology/components/`, (2) update the `-edit` file so that it imports `https://nfdi4culture.de/ontology/cto/components/your-component-name.owl` (the IRI of your new component), and (3) update the XML catalog file (`src/ontology/catalog-v001.xml`) to redirect that IRI to the file in the `src/ontology/components` directory, so that the new component can be found by tools such as Protégé or ROBOT, when they load the `-edit` file.
+
+If your component is to be generated by some automated process, add a goal in your custom Makefile (`src/ontology/cto.Makefile`) and make it perform any task needed to generate the component:
 
 ```
-  <uri name="https://nfdi4culture.de/ontology/cto/components/your-component-name.owl" uri="components/your-component-name.owl"/>
+$(COMPONENTSDIR)/your-component-name.owl: $(SRC)
+	<Insert here the code to produce the component>
 ```
 
-4) Add the component to the edit file (src/ontology/cto-edit.obo)
-for .obo formats: 
+If the component is to be generated from a ROBOT template, the ODK can generate the appropriate code for you. For that, when adding the component fo the ODK configuration file (step 2 above), explicitly indicate that the component should be derived from template(s) and list the source templates:
 
 ```
-import: https://nfdi4culture.de/ontology/cto/components/your-component-name.owl
+components:
+  products:
+    - filename: your-component-name.owl
+      use_template: true
+      templates:
+        - template1.tsv
+        - template2.tsv
 ```
 
-for .owl formats: 
+In this example, the component will be derived from the templates found in `src/templates/template1.tsv` and `src/templates/template2.tsv`. Initial empty templates will automatically be generated when the repository is refreshed (step 3).
+
+Likewise, the ODK can generate the required code for the case where the component is to be derived from SSSOM mappings:
 
 ```
-Import(<https://nfdi4culture.de/ontology/cto/components/your-component-name.owl>)
+components:
+  products:
+    - filename: your-component-name.owl
+      use_mappings: true
+      mappings:
+        - my-mappings.sssom.tsv
 ```
 
-5) Refresh your repo by running `sh run.sh make update_repo` - this should create a new file in src/ontology/components.
-6) In your custom makefile (src/ontology/cto.Makefile) add a goal for your custom make file. In this example, the goal is a ROBOT template.
+and for the case where the component is to be fetched from a remote resource:
 
 ```
-$(COMPONENTSDIR)/your-component-name.owl: $(SRC) ../templates/your-component-template.tsv 
-	$(ROBOT) template --template ../templates/your-component-template.tsv \
-  annotate --ontology-iri $(ONTBASE)/$@ --output $(COMPONENTSDIR)/your-component-name.owl
+components:
+  products:
+    - filename: your-component-name.owl
+      source: https://example.org/component-source.owl
 ```
 
-(If using a ROBOT template, do not forget to add your template tsv in src/templates/)
-
-7) Make the file by running `sh run.sh make components/your-component-name.owl`
-

mkdocs.yml

@@ -35,3 +35,6 @@ extra_javascript:
   #  - optionalConfig.js
   - https://cdn.jsdelivr.net/npm/mermaid@11.12.0/dist/mermaid.min.js
   - extra-loader.js
+
+plugins:
+  - d2