Olivaw-Template

A template repository for projects using Olivaw to support ontology engineering using Acimov methodology.

This repository is affiliated to the Wimmics reasearch team, check the other Wimmics projects.

How to use

This repository is made to help any developer to start an ACIMOV ontology development process, so check the scientific article about the ACIMOV methodology.

This repository also relies on olivaw framework, so check the olivaw repository and its documentation.

Quick start

• Instanciate a repository using the "Use this template" button at the top of the template repository webpage
• Add a repository secret variable named GIST_SECRET containing an access token with the gist scope (see how to add make the token and add the secret)
• Clone the repository locally with git clone ...
• Install olivaw package
• Inside the repository folder, type olivaw init repo and follow the instructions
• Install pre-commit package using the command pip install pre-commit
• Inside the repository folder, type pre-commit install
• Make a first commit to add olivaw parameters file ane enable pre-comit hook:
  • git add README.md .pre-commit-config.yaml .acimov/parameters.json
  • git commit -m "Init commit"
  • git push
• Remove the .github/README.md file

Check the olivaw functional documentation for more details about olivaw CLI and olivaw pre-commit hook.

Add gist scope access token to secret repository variable

• First go to the Github access token generation webpage.
• Then create a personnal access token with only the gist scope. Copy/paste this token somewhere because it will never be shown again.
• Then go to {repository_url}/settings/secrets/actions, create a new repository secret named GIST_SECRET and paste the key

Install olivaw

Olivaw requires python version 3.10 or greater and a Java version 11 or greater

It can be installed using pypi:

pip install olivaw

Installing from GitHub URL is also possible:

pip install git+https://github.com/Wimmics/olivaw

Fill the template files

Different files were made templates so that it can be adapted to any ontology project:

• README: The main file that should present this ontology to anyone discovering the repository
• ONTOLOGY primer: A primer template that will provide all the key concepts explanations to use the ontology
• MODELING-ONTOLOGIES: A document meant to provides general guidelines about how to use the ontology
• ONTOLOGY alignment: A template document that will provide all the required information to align a dataset expressed with a similar ontology with the current project ontology

Finally, the main README.md file that is intended is the README template that can be found in this folder.

Features

Development features

• test run locally against ontology fragments, data fragments and competency questions. Check the olivaw command line documentation for how to run tests, olivaw test documentation for details about what is tested and what the default tests cover, olivaw custom test documentation to see how to add cutomized tests and olivaw parameters documentation to see how to customize the olivaw project parameters.
• pre-commit hook that will prevent blocking errors to be committed on client side to be pushed to origin repository. Check the pre-commit documentation and olivaw pre-commit hook documentation for more details.
• GitHub Actions that will manage the branches initializaton and provide health checks of the different branches at any time. Check the GitHub Actions documentation

Project structure

Many files are already there and may be kept, updated, adapted or removed at will, such as:

• README template that will provide the main element to redact a proper README.md file for the project
• AUTHORS template that should provide the information to developpers and some useful information about the project
• CODE OF CONDUCT that will provide the code of conduct to follow during any interaction during the ontology development
• CONTRIBUTING file that provides the main guidelines to contribute for the ontology
• license file that provides the copyrights that should apply to the project. The default version is LGPL-2.1
• ONTOLOGY primer: A primer template that will provide all the key concepts explanations to use the ontology
• MODELING-ONTOLOGIES: A document meant to provides general guidelines about how to use the ontology
• ONTOLOGY alignment: A template document that will provide all the required information to align a dataset expressed with a similar ontology with the current project ontology
• .gitignore: A file that exclude different files and folders to be commited so that no useless and polluting files are pushed to the repository

Different folders are also present as part of the acimov architecture, namely:

• domains folder that will contain the different application domains and motivating scenarios, check the domains documentation
• src folder that will contain the different modules that are expected to be published
• use-cases folder that will contain all the scenarios that can show the actual abilities of the ontology
• resources folder that is expected to contain the different resources that may be useful for the main README file
• primer folder that will contain the ontology primer and the different alignement documents
• .acimov folder that will contain the different files and folders related to acimov process and olivaw
• .github folder that will contain the different files and folders related to github, including the workflow files

A CITATION.cff at the root of the repository may be also a good idea for any people to cite the ontology properly. Several CITATION.cff files generators exist to make one quite easily.

Parameters

In order to customize this configuration, check the olivaw actions documentation, the olivaw custom test documentation and the olivaw parameters.json documentation.

Contributing

Feel free to open an issue or submit a pull request.