IOF Annotation Properties
- tschneider
The following are the annotations, their IRIs, and guidance for use in IOF ontologies.
General Guidance
The intention of using annotations is to
help a potential user decide if the ontology or a notion therein meets his or her needs and
help a developer understand the ‘elements’ in the ontology and how to interpret them consistent with the intended interpretation of the IOF.
Annotation Usage Conditions
The particular annotations that are required or used will depend on the representation language used. IOF ontologies are published using either OWL or Common Logic. As example, if using Common Logic the iof-av:firstOrderLogicDefinition annotation should not be used.
Formal Definitions – A ‘formal definition’ is a statement or expression made using a formal language.
A Formal Language can be considered as composed of symbols (aka the alphabet, aka signature), logical symbols (for conjunction, disjunction, implication, equivalence, and quantification), non-logical symbols, and a a set of rules for creating (well formed) statements/expressions in the language. In the case of OWL there are non-logical symbols for classes, object properties, and data properties and these non-logical symbols are usually natural language terms or phrases.
For the IOF these formal languages include First Order Logic (FOL), Common Logic (CL), and OWL. Note that the last two are used for ontology development in the IOF.
For classes, the only Formal statements or expressions in an IOF ontology are the OWL or Common Logic (class or relation) axioms and the First Order Logic Definition annotation (if using OWL).
Note, in the case of a primitive or axiomatic notion there will be no (complete) necessary and sufficient formal definition or axioms.
One point to bear in mind in the way the IOF is using formal languages is that the majority of the symbols used are not from the Greek alphabet nor single characters (usually) but are derived from natural language terms or phrases. This distinction must be kept in mind.
There will be some notions (e.g. classes) that are taken as primitive or axiomatic. They will not have Formal definitions, but will have an Elucidation (using the iof-av:elucidation annotation) to explain the intended interpretation.
Acronym Use
While acronyms and other abbreviations may be provided as annotations to elements in an IOF ontology, they must NOT BE USED as part of class or relation IRIs, identifiers, or labels, except where they have become the primary designator for a notion where the full ‘name’ is no longer commonly known or recognized. Examples include, LASER: Light Amplification by Stimulated Emission of Radiation; RADAR: RAdio Detection And Ranging; MODEM: Modulator-DEModulator; SCUBA: Self-Contained Underwater Breathing Apparatus; etc.
Annotation Properties
The following annotations apply to the elements (i.e. classes or relations) in a (published) IOF ontology.
Natural Language Definition – iof-av:naturalLanguageDefinition
This annotation is Required for each non-primitive or non-axiomatic class of an IOF (OWL or Common Logic) ontology.
It is optional for primitive (aka axiomatic) classes since such the Elucidation annotation (iof-av:elucidation) is required and will satisfy the role of a natural language definition.
This annotation is optional, but recommended, for relations when the intent or interpretation of a relation may be misunderstood.
There should be at most one.
The natural language definition should be subject matter expert friendly and consistent with any formal definition or elucidation.
Natural language definitions should use class and relation names with following caveats:
Relations – For those relations whose label (i.e. local identifier) consist of multiple terms hyphenate the terms of the label: e.g. ‘hasPlan’ would be written as ‘has-plan’
Classes – For classes whose label has multiple distinct terms, e.g, ManufacturingOperationSpecification, separate the terms but bound them with apostrophe marks: ‘Manufacturing Operation Specification’.
First Order Logic Definition – iof-av:firstOrderLogicDefinition
The First Order Logic Definition annotation is comprised of the (complete) necessary and sufficient conditions.
This annotation is Required for each non-primitive (aka non-axiomatic) class (i.e. unary relation) of a published IOF OWL ontology. This is the most authoritative and comprehensive definition of an IOF element.
IOF Common Logic ontologies do not require this annotation, but if included it must be logically equivalent to the Common Logic definition.
A primitive (aka axiomatic) term will not have a First Order Logic definition in either an OWL or Common Logic IOF ontology.
There should be at most one First Order Logic definition.
The specific symbols to be used for existential and universal quantification along with those for conjunction, disjunction, negation, conditional (i.e. if-then), and equivalence will be those commonly used in the mathematical formulas and statement.
Conjunction – ∧; Disjunction – ∨; Negation – ¬; Existential Quantification – ∃; Universal Quantification – ∀; Conditional – →; Equivalence – ↔; Left/Right Parentheses – (,); Left/Right Brackets – {,}.
An example of a First Order Logic definition for ‘Product’ might be (again bearing in mind the natural language terms appearing should be regarded as symbols in the IOF signature):
Continuant(x) ∧ ¬(SpecificallyDependentContinuant(x) ∨ Person(x) ∨ Organization(x)) ∧ ∃r (ProductRole(r) ∧ hasRole(x, r))
Semi-Formal Natural Language Definition – iof-av:semi-formalNaturalLanguageDefinition
This annotation is Required if an element in an IOF OWL ontology has a First Order Logic definition or where the element is defined using Common Logic (i.e. in a Common Logic ontology).
The intent of this annotation to provide a transition or bridge from the First Order Logic definition of a element to the natural language definition. This definition is intended to help a user understand the intended interpretation of the element.
As example, using the First Order Logic definition of ‘Product’ above, a semi-formal translation of that might be:
Product =def. Continuant that is not a Person and not an Organization and not a Specifically Dependent Continuant and there is a Product Role that the thing bears.
Elucidation (aka explanation) – iof-av:elucidation
This annotation is Required for primitive/axiomatic class notions.
It is intended to provide guidance or explain (in a natural language style) how to interpret the notion.
It is used for terms without formal logical definitions of Necessary and Sufficient conditions.
The format should include no CamelCase, capitalization, or periods (i.e. do not use common grammar)
The annotation should be used in cases where the complete necessary and sufficient conditions have yet to be determined. As example, in the case of a sub-class at least one necessary condition can be described (e.g. the super or parent class).
Example: From the BFO 2.0 Specification document of 2015, the elucidation of the primitive notion ‘Continuant’:
“A continuant is an entity that persists, endures, or continues to exist through time while maintaining its identity.”
BFO Location – iof-av:relationToBasicFormalOntologyElement
IOF Ontologies are to be published in two versions. One which directly imports and uses the foundational ontology, BFO. And one which does not directly import BFO.
For those versions that do not directly import BFO an annotation must be included that represents the position or location of the class or relation in the BFO hierarchy.
The intent and goal of this annotation is to provide
a) a way for users to understand how the class or relation is related to BFO and thus help in understanding the distinctions made in its definition, and
b) a computer actionable representation to allow reconstruction of the position of the class or relation in the BFO taxonomy
Example: ‘Agent’ is a subclass of the BFO class ‘material entity’, which in turn is a subclass of the BFO class ‘independent continuant’, which in turn is a subclass of the BFO class ‘continuant’. So the position of ‘Agent’ is ‘material entity ← independent continuant ← continuant’.
External Documentation – rdfs:seeAlso
The information provide via annotations in an ontology should be concise and to the point.
Additional or extended explanations, history, decisions, rationale, etc. can be placed in an ontology’s External Documentation.
The External Documentation need not be elaborate. If using Github to publish an ontology is could be part of the Read.Me element. Or it could be a single document.
In most cases the content of this annotation may be a URL (e.g. the GitHub site of the ontology).
Source – dcterms:source
The intent is to provide a user with a reference for the element being annotated,
The ‘Source’ annotations would likely be used as an annotation on an annotation. For instance annotating a Natural Language definition annotation.
Direct Source – iof-av:directSource
The intent of this annotation is to provide the reference to the definitive source of any material used in the development of the element being annotated.
It can be a URL to a standard, common dictionary (e.g. Oxford), or similar reference.
Derived/Adapted Source – iof-av:adaptedFrom
The intent of this annotation is to provide a short description of where, or from what, the entity being annotated was adapted from.
Internal Label – rdfs:label
The de facto use of rdfs:label is to exactly reflect the local name of an element in an ontology (i.e. in OWL the final segment of the IRI after the #, the local name).
Example: If the IRI of a class was www.industrialontologies.org/core#ManufacturedProduct, the rdfs:label might be ‘Manufactured Product’
Example – skos:example
Use of this annotation is optional, but recommended if it will help a user understand the intended interpretation(s).
This annotation should use at most twice with/on a notion.
Additional examples or more elaborate examples should be placed in the External Documentation (using rdfs:seeAlso).
Comment – rdfs:comment
This annotation is optional
It use is not recommended. But if used, use it only once.
This is a catch-all annotation to account for extra information or other bits of useful data to help a user understand the intent of an element.
Synonym – Abbreviation, Acronym, Symbol
Synonym – iof-av:synonym
An alternate label that may help users discover the element.
Abbreviation – iof-av:abbreviation
An alternate short label for the element
Acronym – iof-av:acronym
A specialized abbreviation.
Use this annotation when there is a commonly accepted acronym
The intent is to support a weakly constrained notion of abbreviation that takes the form of a few concatenated letters extracted from the words in the label, regardless of whether the resulting abbreviation is spoken as a word or as a sequence of letters.
Symbol – iof-av:symbol
A terse designation (abbreviation) for the element.
Use this annotation when there is a standard symbol for the element: e.g. chemicals, units of measure, etc.
The following annotations apply to an entire (published) IOF ontology and not to individual elements of the ontology (e.g. at the top of the file).
Copyright – iof-av:copyright
Required for an IOF ontology.
License – dcterms:license
Required for an IOF ontology.
Version – owl:versionInfo
The version information applies to the entire ontology.
The exact format or strategy for formatting has yet to be decided. But at least the month and year of publication should be included.
Additional details about a version of an (entire) ontology can be kept in the External Documentation.
If a Working Group deems it useful to provide version information per notion, such information can be provided in the External Documentation.
