Skip to content

DomainOntologiesBestPractices

Jump to bottom
Emanuele Ghedini edited this page Dec 1, 2025 · 1 revision

Best practices for domain ontology development and maintenance

This section describes a set of best practices for development and maintenance of EMMO-based domain ontologies. They have mainly been developed by MatCHMaker, building on the combined experience from several earlier projects (like MarketPlace, OntoTrans, MaterialsCommons, OpenModel, BIG-MAP, NanoMECommons) collaboration with the sister project CoBRAIN and the development of the MatCHMaker domain ontologies. As seen from Figure 2, the MatCHMaker ontologies not only depend on EMMO, but also on other domain ontologies over which they have no control. This has introduced new challenges on dependency management that have been addressed earlier. A new solution to dependency management has been developed by MatCHMaker and incorporated into these best practices.

To serve as an example, these best practices will guide you through the needed steps for creating and maintaining a new hypothetical domain ontology about black holes.

List of best practices:

Creating a GitHub repository

It is recommended to create a GitHub repository for the domain ontology under the https://github.com/emmo-repo/ GitHub organisation. This will make the domain ontology easier for users to find and also provides additional advantages like making the ontology resolvable via pre-defined redirections from https://w3id.org/.

To create a new repository for an EMMO-based domain ontology you should start by contacting emmo@emmc.eu and ask them to create the repository. As a minimum, you need to provide the following information:

  • A short name of the new domain ontology, e.g. "blackholes"
  • A title (long name) of the domain ontology, e.g. "Domain Ontology for Black Holes"
  • A short description of the domain ontology
  • The email address(es) and GitHub user name(s) of the main developer(s)
  • The project or organisation behind the domain ontology

When creating a domain ontology on https://github.com/emmo-repo/, it is expected that you will follow these guidelines.

To ensure better community support and help with integration into the framework of EMMO-based domain ontologies, it is recommended to create a EMMC task group for the development of the domain ontology. This require that the leader is an organisatory or individual member of EMMC.

For redirections to work, the name of all domain ontologies is prefixed with "domain-". Hence the new repository will be domain-blackholes and the full path to this repository will be https://github.com/emmo-repo/domain-blackholes. You will get full administrative rights for the repository.

Repository layout

The listing below shows the recommended basic layout of a repository for an EMMO-based domain ontology:

domain-blackholes/
├── .github/
├── docs/
│   └── blackholes.md
├── blackholes-dependencies.ttl
├── blackholes.ttl
├── catalog-v001.xml
├── contributors.ttl
├── LICENSE
└── README.md

Figure 8. Suggested basic layout of a repository for an EMMO-based domain ontology on black holes.

Below follows a short description of each of the sub-folders or files:

  • .github/: Optional directory for continuous testing. See Section Continuous testing and continuous deployment (CI/CD) for more details.

  • docs/: Optional directory with additional documentation of the domain ontology.

  • LICENSE: License file. Recommended license is CC-BY-4.0. If you copy the license text literally from the EMMO repository , GitHub will be able to automatically detect the license.

  • README.md: Markdown-formatted file describing the domain ontology. See README.md file in the domain-concrete repository for an example. A minimal README.md file should contain the following points:

    • A title with the name of the domain ontology.
    • A description of the domain ontology. This should include the purpose of the domain ontology, its scope and intended use case.
    • A table listing the version of all imported ontologies. There should be one row for each version of the domain ontology.
    • The license of the domain ontology.
    • Acknowledgments to funding projects.

  • blackholes-dependencies.ttl: Turtle file defining external dependencies by importing them using owl:imports. Dependencies should be defined using owl:versionIRI. Figure 9 shows an example for domain-blackholes.

    @prefix owl: <http://www.w3.org/2002/07/owl#> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .

<https://w3id.org/emmo/domain/blackholes/depencencies> rdf:type owl:Ontology ;
    owl:versionIRI <https://w3id.org/emmo/domain/blackholes/0.0.1/depencencies> ;
    owl:imports <https://w3id.org/emmo/1.0.1> .

    *Figure 9. Example of a dependency files. The only dependency in this example is https://w3id.org/emmo/1.0.1. *

    By defining the dependencies in a separate file, an automated workflow that squashes all the dependencies into a single turtle file stored on GitHub Pages is easily created. The redirections rules will ensure that the generated file on GitHub Pages will be resolvable via the versionIRI (https://w3id.org/emmo/domain/blackholes/0.0.1/depencencies). This way, all dependencies can be loaded with only a single http request. This solves issues with recursively importing all depending domain ontologies and EMMO modules, which firstly is very slow and secondly may fail with a "too many requests" error from GitHub. The latter is already a common reason for failure in the continuous testing of the domain ontologies.

    Furthermore, having all the dependencies defined in a single file, also makes simplifies the dependency management.

  • blackholes.ttl: This is the main file defining the domain ontology. It should import the contributors file.

  • catalog-v001.xml: Catalogue file that maps the owl:versionIRI of the domain ontology modules to their file location. This allows tools like Protégé or EMMOntoPy to find and load the domain ontology modules from the checked out repository on the local file system instead of loading them from the web. This makes opening the domain ontology much faster and more robust. Figure 10 shows a catalogue file for the domain-blackholes example.

    <?xml version="1.0" encoding="UTF-8" standalone="no"?>
<catalog prefer="public"
         xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
  <group id="Folder Repository, directory=, recursive=true,
         Auto-Update=false, version=2" prefer="public" xml:base="">
    <uri name=https://w3id.org/emmo/domain/blackholes/0.0.1
         uri="./blackholes.ttl"/>
    <uri name=https://w3id.org/emmo/domain/blackholes/0.0.1/contributors
         uri="./contributors.ttl"/>
  </group>
</catalog>

    Figure 10. Example of a catalogue file for the domain-blackholes example.

  • contributors.ttl: Turtle file listing contributors that haven't already been defined in any of the dependencies. This file should import the generated dependency file stored on GitHub Pages using its version IRI (https://w3id.org/emmo/domain/blackholes/0.0.1/depencencies). This file does not specify the creators or contributors of the ontology, but it expands the pool of possible contributors or creators. Creators and contributors are then specified in the ontology with dcterms:creator and dcterms:contributor, respectively.

    See e.g. the contributors.ttl file in the in the domain-concrete repository for an example.

What to put under version control

The general rule is that all source files used to develop the ontology should be under version control. This includes documentation and figures.

Generated artefacts, like release versions or inferred ontologies should not be included. GitHub Pages can be used for such files [1]. It is recommended to create a separate branch called gh-pages for deployment to GitHub Pages (the CI/CD workflows assume this branch name). Figure 11 shows how to set up GitHub Pages.

Figure 11. Screenshot of 'Settings' for how to set up GitHub pages for a domain ontology. Create a branch called gh-pages. Under the settings for 'GitHub Pages', select 'Deploy from a branch' as source and then to deploy from the root of the gh-pages branch.

Branching model

The branching model suggested here is adjusted to ontology development and differs slightly from common models in software development. The reason is that the EMMO ontologies rely heavily on w3id redirections and how GitHub URLs are composed.

Figure 12. Recommended git branching model for ontologies.

Figure 12 shows the recommended branching model for ontologies. It involves three types of branches:

  • master: A long-lived branch that reflects the latest release. Pushes to master, except for when creating a new release, should in general be avoided. Updates that only affect the documentation or README file may be acceptable. Such changes should also be merged into the current relevant release branch(es). All releases should be made from master and tagged with a semantic version number, without any prefixing "v".
  • Release branch: A temporary branch used for preparing the next release. It collects all development and changes towards a release. A release branch should be created from master and named after the version number of the upcoming release. Do not prefix the version number with a "v". At the first push to a release branch, the version number in all files in the repository should be updated to the targeted release (tools like regexxer may be handy for this). When it is time to make a release, the release branch should be merged to master and deleted.
  • Feature branch: A temporary branch for development of a new feature. Feature branches should start from and be merged back to a release branch.

The benefit with this branching model is that the development version of the ontology in the release branch will be resolvable and testable during development.

Some tools expect that there exists a release. Hence, it is a good idea to create an initial 0.0.1 release early on in the development.

In collaborative development, it is good practice to require that all pushes to the master and release branches should be done via reviewed pull requests.

Backport a fix to an older release

To backport a fix into an older release, we recommend the following procedure (also shown in Figure 13):

  1. Create a new backport release branch based on the old release that should be fixed. As for standard release branches, name the branch after the intended release version number. Since it only makes sense to backport major and minor releases, the version number of a backport release will typically be the version of the old release with the patch number increased.
  2. Apply the fix, e.g. by cherry-picking.
  3. Test and ensure that everything works as expected.
  4. When everything works, rename the branch (e.g. to "tmp") and create the release tagged with the targeted version number.
  5. Remove the renamed branch.

Figure 13. Recommended git branching strategy for creating backport releases.

Namespaces and IRIs

The namespaces and IRIs of EMMO-based domain ontologies should adhere to the following set of rules:

  • The IRI of a domain ontology hosted on the emmo-repo organisation on GitHub should be prefixed with https://w3id.org/emmo/domain/ followed by the short name of the domain ontology.

    Example: https://w3id.org/emmo/domain/blackholes

  • The owl:versionIRI should equal to the IRI followed by a slash and the version number.

    Example: https://w3id.org/emmo/domain/blackholes/0.9.5

  • Define a namespace prefix for the domain ontology (it is a shorthand for the IRI of the ontology). A prefix is typically 2-5 characters, but there are no formal limits.

    Example: "dobh"

    Note: The prefix can be registered https://prefix.cc/ if it is expected that the domain ontology will be widely used by the community.

  • The base IRI should be the ontology IRI followed by hash.

    Example: https://w3id.org/emmo/domain/blackholes#

  • It is up to the domain ontology developer to select a naming scheme for ontological concepts. It is recommended to either use numerical IRIs (like EMMO) or the preferred label (see Section Annotating entities for conventions for preferred labels). If numerical IRIs is used, it is recommended to prefix them with the prefix followed by and underscore.

    Examples: "DOBH_1246b120_abbe_4840_b0f8_3e4348b24a17" or "BlackHole"

  • The full IRI of an ontological concept is the base IRI followed by the name.

    Example: https://w3id.org/emmo/domain/blackholes#DOBH_1246b120_abbe_4840_b0f8_3e4348b24a17

  • All import statements (using owl:imports) should refer to the version IRI.

Ontology metadata

It is recommended to annotate the EMMO domain ontologies with the below list of metadata. This will increase the FAIRness (as reported by e.g. FOOPS) of the domain ontology and make it easier to find and access.

  • owl:versionIRI: Version IRI. Ex: <https://w3id.org/emmo/domain/blackholes/0.5.0>
  • dcterms:abstract: Description of the ontology. The description in the README file can be reused.
  • dcterms:created: When the ontology was created. Ex: "2024-01-07"^^xsd:date
  • dcterms:contributor: People who have contributed to the domain ontology (but are not main authors). Refer to people using the IRIs defined in the contributors.ttl file. Ex: :SophieSchmid
  • dcterms:creator: Main authors of the domain ontology. Ex: :AlexandreOuzia, emmo:FrancescaBleken, emmo:JesperFriis
  • dcterms:issued: Date of the first release: Ex: "2025-03-10"^^xsd:date
  • dcterms:license: URL to license description. Ex: <https://creativecommons.org/licenses/by/4.0/legalcode>
  • dcterms:mediator: The entity that mediates access to the resource. If the domain ontology is hosted on https://github.com/emmo-repo/, it is EMMC. Ex: emmo:EMMC_ASBL
  • dcterms:modified: Date of last release: "2025-08-23"^^xsd:date
  • dcterms:publisher: The entity responsible for making the ontology available. Typically, the project that created the resource. Ex: <https://he-matchmaker.eu>
  • dcterms:source: Related resources from which the described ontology is derived. Like standards, books, web sites, etc. Ex: <https://en.wikipedia.org/wiki/Black_hole>
  • dcterms:title: Title of the domain ontology. Ex: "Domain Ontology for Concrete (DOC)"@en
  • bibo:bibliographicCitation: Reference to publication describing the domain ontology. If there are no publications (yet), you can refer to the resolvable DOI on Zenodo. Ex: <https://doi.org/10.5281/zenodo.16932399>
  • bibo:doi: DOI for the domain ontology. Ex: "10.5281/zenodo.16932399"
  • bibo:status: Status of the domain ontology. Typically "unstable" or "stable". Ex: "unstable"
  • vann:preferredNamespacePrefix: Preferred namespace prefix for the domain ontology. Ex: "dobh"
  • vann:preferredNamespaceUri: IRI of the ontology: Ex: "https://w3id.org/emmo/domain/blackholes"
  • owl:versionInfo: Version info. Ex: "0.5.0"

Annotating entities

All entities (classes, properties and individuals) in the ontology should be annotated. The list below includes common annotations used in domain ontologies:

  • skos:prefLabel [Mandatory]: Preferred label. All classes and properties should have one and only one preferred label. They should be valid identifiers [2], be unique within the namespace and adhere to the following naming conventions:
    • Classes: should be singular nouns and written with CamelCase.
    • Properties: should be lowerCamelCase. They often start with "has", like hasProperty (with the inverse written as isPropertyOf).
    • Individuals: should be written as lowercase_with_underscores.
  • skos:altLabel [Recommended]: One or more alternative labels. This may include acronyms, abbreviations, spelling variants, and irregular plural/singular forms.
  • emmo:elucidation [Mandatory]: Short enlightening explanation aimed to facilitate the user in drawing the connection (interpretation) between an OWL entity and the real-world object(s) for which it stands.
  • skos:example [Recommended]: An example of the use of a concept.
  • emmo:definition [Optional]: Precise and univocal description of an ontological entity in the framework of an axiomatic system.
  • emmo:comment [Optional]: A text providing additional information about the entity.
  • emmo:conceptualisation [Optional]: A comment that helps the reader to understand how the world has been conceptualised by the ontology authors.
  • emmo:etymology [Optional]: Explanation of the origin of a word and the historical development of its meaning. It is usually applied to labels, to better understand the connection between a label and the concept it concisely represents.
  • emmo:illustration [Optional]: A link to a .png file aimed to facilitate understanding of the concept, or of an annotation.

Versioning

Use semantic versioning for all version numbers. For details, see https://semver.org/.

Short summary:

  • Version numbers are written MAJOR.MINOR.PATCH. May contain an optional pre-release version or build metadata. Examples: 0.0.1, 0.3.14, 1.10.2-beta
  • Major version is increased for backward incompatible changes.
  • Minor version is increased for backward compatible changes.
  • Patch version is only increased for backward compatible bug fixes.

Continuous testing and continuous deployment (CI/CD)

It is highly recommended and easy to set up CI/CD for your domain ontology. A toolkit is under development that will simplify setting up the CI/CD even further. For now, follow these steps:

  1. Create a branch named gh-pages and enable GitHub Pages as described in Section What to put under version control.

  2. Copy the .github/ directory from e.g. domain-concrete into the repository for the domain ontology. This can be achieved by running the commands listed in Figure 14.

    # Name of domain ontology, replace "blackholes" with name of your ontology
name=blackholes

# Go to root of git repository for the domain ontology
cd domain-$name

# Download and extract .github subdirectory from domain-concrete
wget https://github.com/emmo-repo/domain-concrete/archive/refs/heads/master.zip
unzip master.zip 'domain-concrete-master/.github/*'
mv domain-concrete-master/.github/ .
rm -r domain-concrete-master/ master.zip

# Update workflow files
sed -i "s/concrete/$name/" .github/workflows/*.yml

# Commit to GitHub
git add .github
git commit -m "added ci/cd"
git push origin master

    Figure 14. Commands for setting up CI/CD workflow in a GitHub repository for an EMMO-based domain ontology.

This will create a .github/` directory and setup a CI/CD system that will:

  • For all commits: check that the ontology adhere to EMMO conventions using the emmocheck tool.
  • For commits to master/main: generate turtle files on GitHub Pages (dependencies, squashed ontology and inferred ontology).
  • For new releases: ensure traceability by saving a copy of the generated files for the released version.

Additional CI/CD workflows are planned to be added in the near future, including:

  • For all commits: Check dependencies.
  • For all commits: Automatically update to latest version of the CI/CD workflow (should be configurable).
  • For commits to master/main: Generate reference documentation.
  • For commits to master/main: Generate dependency diagram/table.
  • For new releases: Automatically register the new version in ontology registries.

Give feedback and propose improvements to these best practices

These best practices are not carved in stone. If you have any feedback or suggestion for improvement, feel free to create an issue or pull request on https://github.com/emmo-repo/EMMO or contact the EMMO core group by sending an email to emmo@emmc.eu.

[1]: Deploying to GitHub Pages using a branch, is in principle in contradiction to the statement above that generated artefacts should not be under version control. However, the CI/CD workflow described in Section 2.5.9 will clear the git history for each release.

[2]: A valid identifier should match the regular expression: [a-zA-Z_][a-zA-Z0-9_]*

This Wiki is released under the Creative Commons Attribution 4.0 International (CC-BY-4.0) license.

Guidelines for Domain Ontology Developers

Clone this wiki locally