Skip to content

[deprecated] How to Contribute

Jump to bottom
Pedro Paulo Favato Barcelos edited this page Jul 21, 2023 · 1 revision

How to contribute to the OntoUML/UFO Catalog

On this page you can find the following content:

Tool requirements

  • Visual Paradigm: A multi-platform modeling tool, in which the ontology models must be designed. Visual Paradigm provides a free community edition version that can be downloaded here.

  • OntoUML Plugin: An extension of Visual Paradigm that adds support for OntoUML modeling. You can find its download page and installation instructions here.

  • Git (OPTIONAL): A distributed version control system.

  • GitHub (OPTIONAL): A provider of Internet hosting for software development and version control using Git. You will need a GitHub account to submit your models, which you can create here.

  • Git Client (OPTIONAL): To help you use Git, you can use a desktop client. Good free alternatives are GitHub Desktop and GitKraken.

How to submit an ontology

You can submit an ontology through GitHub (preferable) or through the catalog's contribution form.

Contributing through GitHub

Even though more technical, the contribution through GitHub has advantages and, hence, is preferable. If you have the technical skills for using this channel, please do not refrain from using it. For contributing:

  1. Fork the ontouml-models repository. Detailed instructions are available here.

  2. Clone your forked repository into your computer. You can do this via a terminal (instructions here) or a Git client.

  3. Create your ontology directory according to these instructions. Always document the latest version of the ontology.

  4. Commit your local changes.

  5. Push your local changes to GitHub. Instructions are available here.

  6. Open a pull request from your fork to the ontouml-models repository. Instructions are available here. Please create a single pull request per ontology.

  7. A moderator will review your submission and, if it complies with the guidelines listed below, will accept, and merge it into the ontouml-models repository. Moderators may ask you to adjust the contents of your submission.

Contributing through the catalog's form

You can send us an ontology by using the catalog's contribution form. The use of the catalog is intended for anyone who wants to contribute in a simplified way.

How to structure an ontology directory

The information contained in this section concerns only submissions through GitHub. If you are using the catalog, you can skip this section

Each directory regards a single ontology.

The name of this directory must always be in lowercase letters and should be either (in order of preference):

  1. ontology's author name + year + ontology's short name (e.g., albuquerque2015ontobio), or
  2. ontology's short name + year (e.g., soccer-ontology2016), or
  3. ontology's short name, when the development year is unknown (e.g., soccer-ontology).

It MUST contain the following files and folders:

  • metadata.yaml: a file containing the ontology's metadata (see more details about this file here).
  • ontology.vpp: a file containing the Visual Paradigm project of the ontology.
  • references.bib: a file containing the BibTeX citation data for each publication about the ontology. This file is not required for ontologies that were not published.
  • original diagrams/: a folder containing figures of the diagrams created by the authors of the ontology (only diagrams that were used). Keep the original diagram names whenever available.

Here is what your ontology directory should look like:

author2015title/
|   metadata.yaml
|   ontology.vpp
|   references.bib
+---original diagrams/
       diagramName1.png
       diagramName2.png
       diagramName3.png

The ontology metadata file

The ontology's metadata must be registered by the collaborator in a metadata.yaml file, which must have the following fields:

  • title: The title of the ontology as given by its authors or by the documenting person.

    • Mandatory field.
    • The value must be a string.
    • Examples: Common Ontology of Value and Risk, Music Ontology Refactored 
      title: Common Ontology of Value and Risk

  • acronym: The acronym of the ontology's title as used by its authors.

    • Optional field.
    • The value must be a string.
    • Examples: UFO-S, RDBS-O, OntoVCM 
      acronym: OntoVCM

  • issued: The year of the first publication of the UFO or OntoUML ontology.

    • If the ontology was first released using another formalization language, report the case in the editorialNote field.
    • Optional field.
    • The value must be a positive integer with 4 digits. 
      issued: 2014

  • modified: The year of the most recent publication of the ontology.

    • Must be used only when the issued version was modified.
    • Optional field.
    • The value must be a positive integer with 4 digits. 
      modified: 2018

  • contributor: a list of URIs of anyone who contributed to the development of the model.

    • Optional field.
    • Each list entry must be a URI or a URL referencing a single contributor.
    • Use the contributor's URI provided by DBLP (preferably), by ORCID, or by another provider. If there are no URIs that identify the contributor, use the URL of one of hers/his pages (e.g., ResearchGate or LinkedIn). Strings are not allowed in any case.
    • A list of URIs for each contributor already identified can be seen in List of UFO and OntoUML Ontology Models spreadsheet, Author's URI tab. 
      contributor:
 - https://dblp.org/pid/253/7047
 - https://orcid.org/0000-0003-1868-7018

  • keyword: The list of domains covered in the ontology.

    • Mandatory field.
    • Each list entry must be a string. Examples: services, value, risk, music. 
      keyword:
 - robotics
 - technology

  • theme: Library classification of the main ontology subject (domain) according to the Library of Congress Classification System (LCC).

    • Mandatory field.
    • The allowed values are: Class A - General Works, Class B - Philosophy, Psychology, Religion, Class C - Auxiliary Sciences of History, Class D - World History and History of Europe, Asia, Africa, Australia, New Zealand, etc., Class E - History of America, Class F - History of the Americas, Class G - Geography, Anthropology, and Recreation, Class H - Social Sciences, Class J - Political Science, Class K - Law, Class L - Education, Class M - Music, Class N - Fine Arts, Class P - Language and Literature, Class Q - Science, Class R - Medicine, Class S - Agriculture, Class T - Technology, Class U - Military Science, Class V - Naval Science, Class Z - Bibliography, Library Science, and General Information Resources. 
      theme: Class T - Technology

  • editorialNote: General notes on the ontology documentation process.

    • Optional field.
    • Any information that you consider important for later users can be registered in this field. There are no restrictions on its use. Note that this field is not a list and, hence, all information must be kept in the same line.
    • The value must be a string. 
      editorialNote: The ontology was originally designed in Portuguese.

  • ontologyType: The list of types that apply to the ontology, either claimed by the authors or assessed by the documenting person.

    • Mandatory field.
    • The allowed values are: core, domain, and application. 
      ontologyType:
- domain

  • language: The language in which the lexical labels of the ontology (e.g., classes and associations' names) are written.

  • designedForTask: The list of goals that motivated the development of the ontology.

    • Mandatory field.
    • The allowed values are: conceptual clarification, data publication, decision support system, example, information retrieval, interoperability, language engineering, learning, ontological analysis, and software engineering.
    • For choosing the correct designedForTask value, please refer to their descriptions available here. 
      designedForTask:
 - conceptual clarification
 - ontological analysis

  • context: The list of contexts in which the ontology was developed.

    • Mandatory field.
    • The allowed values are: research, industry, classroom 
      context: 
 - research

  • source: a list of URIs or URLs of the resources that contain or present the ontology.

    • Optional field.
    • A single entry must be provided for each reference contained in the references.bib file (when available). In the case where the Ontology is not published and, consequently, does not have references, this field must be left blank.
    • If the ontology was previously published using a representation language different than UFO or OntoUML, the related references can be here added.
    • Use the source's URI provided by DOI (preferably), by DBLP, or by another provider. If there are no URIs that identify the source, preferably use the URL of a page that identifies the source (e.g., in ResearchGate) or, in the last case, use the document's PDF file. 
      source:
- https://doi.org/10.1109/HICSS.2015.453
- https://dblp.org/rec/conf/ontobras/AlbuquerqueSJ16 
- https://tede.ufam.edu.br/handle/tede/2887
- https://www.researchgate.net/profile/Marcos/publication/Novas-Contribuicoes.pdf

  • representationStyle: The list of representation styles adopted in the ontology.

    • Mandatory field.
    • A representation style option must be selected only when a relevant amount of elements in the ontology uses it.
    • The allowed values are: ontouml if the ontology was designed only using OntoUML stereotypes; or ufo if the ontology was developed by extending UFO base categories. 
      representationStyle:
 - ontouml

  • landingPage: a URL of a web page to gain access to the ontology, its distributions and/or additional information.

    • Optional field. 
      landingPage: https://dev.nemo.inf.ufes.br/seon/DPO.html

  • license: a URI or URL that identifies the ontology's license.

    • Optional field.
    • If your work does not have a license yet, you can use choosealicense.com for choosing one.
    • For a non-restrictive license, we recommend the adoption of the CC BY 4.0. 
      license: https://creativecommons.org/licenses/by/4.0/

An example of a complete and well-formed metadata.yaml file can be seen here.

Metadata general observations

In YAML syntax, all members of a list are lines beginning at the same indentation level starting with a "- " (a dash and a space). All fields that require the insertion of values as lists must follow this syntax.

Note that optional fields should be kept in the file without any value, as can be seen in the acronym field shown in the example below. Please do not use null and "" (empty string) in any field.

title: My Ontology
acronym:
issued: 2013

A complete metadata.yaml file must look like the one from the Ontology of Money and Virtual Currencies represented below:

title: Reference Ontology of Money and Virtual Currencies
acronym: ROME
issued: 2020
modified:
contributor:
 - https://orcid.org/0000-0003-0460-2271
 - https://orcid.org/0000-0002-5385-5761
 - https://orcid.org/0000-0002-3452-553X
 - https://orcid.org/0000-0003-3655-0218
 - https://orcid.org/0000-0003-0214-8853
keyword:
 - money
 - virtual currencies
 - finance
theme: Class H - Social Sciences
editorialNote: The ontology was documented based on the GitHub repository (https://github.com/unibz-core/money-ontology).
ontologyType:
 - domain
language: en
designedForTask:
 - conceptual clarification
context:
 - research
source:
 - https://doi.org/10.1007/978-3-030-63479-7_16
 - https://dblp.org/rec/conf/vmbo/AmaralSGPG20
 - https://dblp.org/rec/conf/vmbo/AmaralSG21
representationStyle:
 - ontouml
landingPage: https://github.com/unibz-core/money-ontology
license: https://creativecommons.org/licenses/by/4.0/

Metadata designedForTask field

Please take into consideration the following descriptions for choosing the correct value for the ontology's designedForTask metadata field:

  • conceptual clarification: the modeler had the objective to represent, define or document a domain, to create a domain ontology or reference model.
  • data publication: the modeler had the objective to organize or categorize data to be further publicly published using semantic web technologies (e.g., for linked data) or not (e.g., databases, JSON, or XML files).
  • decision support system: the modeler aimed at organizing or categorizing data for (manual or automated) inferencing or reasoning purposes. It is a specific type of software engineering purpose.
  • example: the modeler created an artificial scoped model for educational, demonstration, or exemplification purposes.
  • information retrieval: the modeler created the model for using its concepts to annotate or classify data from other sources or databases, intending to be able to better query and retrieve information. It is a specific type of software engineering purpose.
  • interoperability: the modeler intended to create an ontology to support interoperability between systems, specifications, languages, standards, or other models.
  • language engineering: model built to be used in the design of a domain-specific or modeling language.
  • learning: the model was created for knowledge improvement purposes, for learning, teaching, or training the modeling language or technologies.
  • ontological analysis: the modeler had the intention to represent existent languages, systems, standards, vocabularies, laws, definitions, or thesauri to expose or correct possible ontological deficiencies.
  • software engineering: model build to describe, design, or implement a piece of software, like an API, a database, etc.

The references file

All bibliographical references related to the ontology being sent must be presented in a single file named references.bib using the BibTeX syntax. This file must not be part of a submission of an ontology that has not been published - please do not send files without any content.

When listing the references of an ontology, please go through its citations on Google Scholar to see if the ontology has updates or extensions by the same authors. Always document the latest version of the ontology.

Here is what the references.bib file for the UFO-S ontology would look like:

@inproceedings{amaral2020reference,
	title        = {A Reference Ontology of Money and Virtual Currencies},
	author       = {Amaral, Glenda and Prince Sales, Tiago and Guizzardi, Giancarlo and others},
	year         = 2020,
	booktitle    = {The Practice of Enterprise Modeling},
	publisher    = {Springer International Publishing},
	address      = {Cham},
	pages        = {228--243},
	doi          = {10.1007/978-3-030-63479-7_16},
	isbn         = {978-3-030-63479-7}
}
@inproceedings{amaral2020towards,
	title        = {Towards a reference ontology of money: monetary objects, currencies and related concepts},
	author       = {Amaral, Glenda and Sales, Tiago Prince and Guizzardi, Giancarlo and others},
	year         = 2020,
	booktitle    = {14th International Workshop on Value Modelling and Business Ontologies (VMBO 2020)},
	volume       = 2574,
	url          = {http://ceur-ws.org/Vol-2574/short17.pdf}
}
@inproceedings{amaral2021towards,
	title        = {Towards Ontological Foundations for Central Bank Digital Currencies},
	author       = {Amaral, Glenda and Sales, Tiago Prince and Guizzardi, Giancarlo},
	year         = 2021,
	booktitle    = {15th International Workshop on Value Modelling and Business Ontologies (VMBO 2021)},
	volume       = 2835,
	url          = {http://ceur-ws.org/Vol-2835/paper9.pdf}
}

For collecting a BibTeX reference, we recommend the dblp.org (preferably), its publisher website, or the Google Scholar.

For cleaning up and organizing BibTeX references before including them in the references file, we recommend the BibTeX Tidy tool.

How to recreate an ontology on Visual Paradigm

When recreating an already published ontology, please be aware of the following instructions. We want the OntoUML/UFO Catalog to be as truthful as possible to the original ontologies. So, please remember to:

  • Not reinterpret the model you are recreating.

  • Use the same stereotypes the authors used, except for:

    • Capitalization differences (e.g., «Subkind» or «SubKind» should be added as «subkind»)
    • Renamed stereotypes (see the list here)

  • Classes or associations without stereotypes must be represented just like they are.

  • Keep syntactical and grammatical errors.

  • Create only the diagrams created by the authors. If the ontology is presented in a paper, create one diagram per figure containing a fragment of the ontology.

  • Stick with the original diagram layout as much as possible, including crossing lines and "ugly" layout decisions.

  • Keep the original language used in the model.

  • Add any notes, constraints, and rules present in the original model as notes in the new model.

  • Only assume that a generalization set exists in the original model if it is represented as a label or via constraints ({disjoint, complete})

Examples and counterexamples of the representation of generalization sets in OntoUML diagrams.

  • If only the label of a generalization set is shown in a diagram, assume that it is isDisjoint = false and isCovering = false.

  • If the multiplicity on an association end is not visible, it MUST be set to unspecified in the recreated diagram.

Before recreating an ontology in Visual Paradigm, please also read carefully our Frequent Asked Questions (FAQ) section.

How to generate the diagrams' images

  • Use Visual Paradigm's embedded feature to export diagrams. It can be found on the Project > Export > Diagrams as Image. Please select the following options:
    • Export type: PNG with Background
    • DPI: 300
    • Graphics Antialiasing: checked
    • Text Antialiasing: checked
Clone this wiki locally