Vocabulary checklist of metadata properties back to ToC

In this section we list the metadata terms we consider relevant for describing a vocabulary.

Vocabulary access

Properties designed to tell anyone how to access your vocabulary. It is true that if a human accesses it and goes through it in detail, she/he will probably figure out which is the main vocabulary and which are the imported or extended ontologies. But from a machine perspective, this is harder. Why not make things easy for everybody?

Vocabulary namespace URI [RECOMMENDED]

Property defining the main URI of your vocabulary. This becomes important in cases when you use permanent URLs: the vocabulary local URI hosting the file may not be the main URI you want people to access when resolving it. The vann vocabulary has a very nice property for describing this, and it is encouraged by the LOV best practices [Vandenbussche and Batant 2012]. Please note that the value must be a literal, not a resource (URL).

Prefix [RECOMMENDED]

Preferred prefix used to refer to the ontology. This is important to let potential reusers know how you expect your ontology to be abbreviated. You want everyone to refer to it in the same way.

Vocabulary goals and description

Once your vocabulary can be properly identified, it is important to describe what it does without forcing users to explore it thoroughly. For this purpose, the following properties are recommended:

Title [RECOMMENDED]

If you were writing a paper describing your ontology, what would be the title?

Description [RECOMMENDED]

A small paragraph indicating what the ontology does and why should some one use it

Abstract [OPTIONAL]

Similar to a description, but with a little bit more background and an explanation about the resued/extended vocabularies, context and applications using this ontology. It can be considered as the abstract of the paper describing you ontology.

Status [OPTIONAL]

Indicates the status of the vocabulary (Recommnedation, Draft, etc.)

Vocabulary version

Your vocabulary may evolve and go through several releases. Knowing which version of the vocabulary is the one being operated with may help debugging and solving compatibility issues.

Version IRI [RECOMMENDED]

The IRI that identifies this version of your vocabulary.

Version info [RECOMMENDED]

Details about the version being handled. We recommend to include, for example, the version number of the ontology (e.g., 1.0.1).

Backward compatibility [OPTIONAL]

Property useful to determine whether this version of the vocabulary is compatible with a previous one.

Incompatibility [OPTIONAL]

Property useful to let a potential reuser that this version of the vocabulary is not compatible with a previous (or future) version.

Vocabulary provenance

Several aspects of the vocabulary's provenance may be very useful to gather insight from the vocabulary. We describe them in this section.

Previous version [RECOMMENDED]

Adding a link to a previous version helps to see how the vocabulary has changed from one to the other. Thanks to this relationship, tools like WIDOCO may create automated changelog sections in the documentation of an ontology.

Creation date [RECOMMENDED]

Date when the vocabulary was created. There are different ways in which the date may be represented, but typically is with an xsd:dateTime literal. Note that some vocabularies, like schema.org, define their own object as range for the date property. We advise to look at the respective vocabulary specifications for more information.

Modification date [OPTIONAL]

Date when your vocabulary was modified. If you review several times a vocabulary, it would be advisable to know when it was last reviewed.

Issued date [OPTIONAL]

Date of formal issuance, like publication. It may be useful to distinguish between the date of creation versus the official date of publication of your vocabulary.

Source [OPTIONAl]

Property indicating where the terms of your vocabulary come from. For example, if your vocabulary implements an existing non-RDF standard, or if there is an active discussion of the terms in a separate collaborative wiki, you may want to add a pointer to them in your vocabulary.

Vocabulary attribution

A key aspect of the medatata should specify the roles of the scientists that have participated in its creation. Having this metadata can facilitate other scientists to provide the approapriate credit to the contributors of the vocabulary.

Creators [RECOMMENDED]

People who created the vocabulary. Adding this metadata property is critical for other potential reusers to provide accurate credit and know who to contact in case of questions.

Contributors [RECOMMENDED]

People who contributed to the development of the vocabulary. Even if contributors may not play a critical role in the vocabulary development, it is important to acknowledge their contribution as well.

Publisher [OPTIONAL]

Organization responsible for publishing the vocabulary. This property is optional, as there are many cases where no organization is involved when publishing a vocabulary.

Vocabulary citation

Ontologies are considered software, and should be cited as such [Smith et al 2016]. However, researchers reusing the ontology may not refer to the correct citation associated to it. Adding metadata to help them would address this issue, granting you the appropriate credit for your work.

DOI [OPTIONAL]

Digital Object Identifier associated to the vocabulary.

Bibliographic citation [OPTIONAL]

Property indicating the text with the citation itself.

Vocabulary license [RECOMMENDED]

Adding a license to your vocabulary is very important, since it tells potential reusers under which terms the ontology may be used, how they should provide attribution to the original author and under which terms they have to license their own work as well.

Vocabulary visualization

Existing tools like WebVowl create excellent interactive diagrams of ontologies, but sometimes the authors may want to simplify them. You may use some of the properties below to associate different types of images to the vocabulary documentation.

A logo that represents the vocabulary and helps people quickly identify it.

Vocabulary diagram [OPTIONAL]

A visualization of the vocabulary.

Similar resources (See also) [OPTIONAL]

Property used to add pointers to similar resources. It may be helpful for the reader, in order to read related state of the art.

Term checklist of metadata properties back to ToC

These metadata terms are targeted towards describing the classes, properties and data properties of the ontology. Adding them as part of the ontology is crucial for potential reusers:

Label [RECOMMENDED]

A human readable label of the term.

Term definition [RECOMMENDED]

Definition of the term. We recommend it to be as precise as possible, in order to avoid possible misunderstandings when reusing the ontology.

Term original source [RECOMMENDED]

Source used to define the ontology term. This property is also used for crawlers, in order to refer to the ontology document in case they stumble upon a term.

Term example [OPTIONAL]

It is always helpful to add examples on the intended usages of the ontology. Pointers to real examples are also valuable.

Term usability

Different versions of the vocabulary may lead to remove or add new terms. In some cases, old terms are left with a "deprecated" tag for legacy purposes. New terms may have different status (e.g., testing), depending on the maturity of the vocabulary. The metadata terms below are typically used for this purpose.

Deprecation [OPTIONAL]

Boolean property that indicates whether a term has been deprecated or not.

Status [OPTIONAL]

Property indicating the usage status of the term. For example, whether the term is mature enough, whether it is has been deprecated, curated, etc. Note that some of the properties proposed below, such as obo:IAO_0000114, have as range a set of fixed values.

Term rationale [OPTIONAL]

A sentence or paragraph explaining why the term was added to the vocabulary. This is key in standard vocabularies, where there is a lot of discussion, because it may record the conclusion of a discussion that led to the addition of the term.