Annotation Vocabulary (AV)
The IOF Annotation Vocabularyprovides a set of OWL annotation properties for annotating IOF or other content with metadata to facilitate user and ontology developer understanding.
Elisa Kendall, Thematix Partners LLC
Evan Wallace, NIST
IOF Technical Oversight Board (TOB)
Todd Schneider, Engineering Semantics, LLC
Industrial Ontology Foundry
Industrial Ontology Foundry (IOF) Annotation Vocabulary
2022-03-31: added new annotations perperties as per "Annotations Vocabulary Version 1."
2022-09-30: added new annotations and supporting constructs, and modified others to match revised guidance in the IOF Confluence page entitled: "Annotations Vocabulary Version 2"
2022-10-31: revised the IRI structure to correspond to the approved approach to IRI representation documented in https://oagiscore.atlassian.net/wiki/spaces/IOF/pages/3564372109/IRI+Structure+and+Format and ran the RDF serialiser (from FIBO) over the content.
2022-11-30: changed various annotations properties to match revised guidance for formalizing terms as per "Annotations Vocabulary Version 2.1"
Copyright (c) 2022, 2023, Open Applications Group
1. The intention of using annotations is to a) help a potential user decide if the ontology or a notion therein meets his or her needs and b) help a user or developer understand the 'elements' in the ontology and how to interpret them consistent with the intended interpretation of the IOF. 2. 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, the iof-av:firstOrderLogicDefinition should not be used in ontologies using Common Logic. 3. Formal Definition – 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. a) 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. b) For classes, the only Formal statements or expressions in an IOF ontology are the First Order Logic Definition annotation and the OWL or Common Logic (class or relation) axioms. Note, in the case of a primitive or axiomatic notion there will be no (complete) necessary and sufficient formal definition or axioms. c) 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. 4. There will be some notions (e.g. classes) that are taken as primitive. They will not have Formal definitions, but may have formal axioms to constrain the intended interpretation.
abstract
summary of the resource
This annotation is used to describe an artifact such as a vocabulary, ontology, or ontology module.
contributor
entity responsible for making contributions to the resource
creator
entity responsible for making the resource
description
account of the resource
issued
date of formal issuance of the resource
license
legal document giving official permission to do something with the resource
modified
date on which the resource was changed
publisher
entity responsible for making the resource available
Used to document the primary agent (organization or person) responsible for the resource. This will be "Industrial Ontology Foundry" for IOF artifacts.
references
related resource that is referenced, cited, or otherwise pointed to by the described resource
rights
information about rights held in and over the resource
source
related resource from which the described resource is derived
The intent is to provide a user with a reference as to how the thing being annotated was derived or arrived at. - The source can be a URL to a standard, common dictionary (e.g. Oxford), or similar reference. Or it can be a short description of where the entity being annotated was derived from. - The 'Source' annotation would most likely be used as an annotation on an annotation. For instance annotating a Natural Language definition annotation.
title
name given to the resource
Used for formal title of an artifact (but not individual elements such as classes or properties).
comment
instance of rdf:Property that may be used to provide a human-readable description of a resource
Use of this annotation is deprecated in IOF. This annotation MUST NOT be used in IOF ontologies. IOF authors SHOULD use explanatoryNote, usageNote, or scopeNote when additional information about the resource is needed. skos:note may be used directly in a case where none of the other annotation properties enumerated apply.
is defined by
instance of rdf:Property that is used to indicate a resource defining the subject resource
This annotation is used to identify the machine readable resource that formally defines the subject resource. The object of an rdfs:isDefinedBy annotation must be a URL.
label
instance of rdf:Property that may be used to provide a human-readable version of a resource's name
Example: If the IRI of a class was https://www.industrialontologies.org/ontology/core/Core/ManufacturedProduct, the rdfs:label might be 'manufactured product'
The de facto use of rdfs:label is to exactly reflect (but not necessarily be exactly the same as) the local name of an element in an ontology (i.e., in OWL the 'local name' is the final segment of the IRI after the /).
see also
instance of rdf:Property that is used to indicate a resource that might provide additional information about the subject resource
The information provided 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. - The object of an rdfs:seeAlso annotation must be a URL (e.g. the reference document or GitHub site of the ontology).
alternative label
alternative lexical label for a resource
change note
note about a modification to a concept
definition
statement or formal explanation of the meaning of a concept
editorial note
note for an editor, translator, or maintainer of the vocabulary
example
example of the use of a concept
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).
note
general note, for any purpose
scope note
note that helps to clarify the meaning and/or the use of a concept
Use of this annotation is optional, but recommended if it will help a user understand the scope and/or context for usage of the concept.
maturity level
classifier used to specify the state of a resource in its development process
provisional
construct or ontology development state in which content is subject to change and may change considerably
IOF users should be aware that the resource is not dependable, but can be used for reference and for further work.
released
construct or ontology development state in which the resource is stable, usable, and has been made available to external users
Release notes will be provided for any changes concerning released content, and any revisions will be backward compatible with the prior version to the degree possible.
abbreviation
synonym that is an alternate short label for the resource
acronym
an abbreviation usually formed from the initial components of a longer name or phrase
Use this annotation when there is a commonly accepted acronym. HOWEVER: While acronyms and other abbreviations may be provided as annotations to elements in an IOF ontology, they must NOT BE USED as part of 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. (e.g. LASER: Light Amplification by Stimulated Emission of Radiation; RADAR: RAdio Detection And Ranging; MODEM: Modulator-DEModulator; SCUBA: Self-Contained Underwater Breathing Apparatus; etc),
adapted from
source for the resource that was modified to create the subject resource
copyright
exclusive legal right, given to an originator or an assignee to print, publish, perform, film, or record literary, artistic, or musical material, and to authorize others to do the same
This annotation is to be used for an entire ontology and not individual elements.
example that refutes or disproves a concept in some scenario and is intended to demonstrate how the concept might be misused
direct source
definitive source of the subject resource
elucidation
'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'.
This annotation is no longer used. The isPrimitive annotation is now set to true to indicate a primitive class when necessary and sufficient conditions can not be provided.
excerpted from
source of a resource that was imported unmodified from an external ontology
This annotation is to be used when an element from a non-IOF ontology is used in an IOF ontology (and the source ontology is not imported in its entirety).
explanatory note
note that provides additional explanatory information about a given notion or resource
first-order logic axiom
logic axiom annotation written in first order logic
First-order logic axioms MAY be provided if the term is primitive ('is primitive' is true ) or non-primitive. A construct MAY include more than one first-order logic axiom annotation.
first order logic definition
logic definition that expresses the axioms of a class or an object property in first order logic
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))
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 - {,}.
is primitive
boolean flag indicating that necessary and sufficient conditions are not provided
'is primitive' must be present if the term does not have necessary and sufficient conditions and the value of the annotation must be set to true. When 'is primitive' is set to true, a value for a 'primitive rationale' annotation must also be provided.
logic axiom
logical statements constraining the interpretation of the notion represented by the construct that do not provide necessary and sufficient conditions
This annotation property is an abstraction of the more specialized logic axiom annotations used in IOF. However, this annotation property can also be used to group together the logic axiom annotation values of different forms (such as FOL and natural language) that express the same meaning for a particular construct.
A first order logic axiom expression and a semi-formal natural language axiom expression should be added as Property values for each logic axiom annotation using 1 of each of the corresponding logic axiom annotation subproperties.
logic definition
definition in the form of a logical expression
maintainer
entity responsible for maintaining the resource
This annotation applies to an entire IOF ontology (i.e. the file) and not to individual elements.
maturity
annotation property used to indicate the development status of a resource
Any value for maturity MUST be an instance of MaturityLevel. All IOF ontologies MUST include exactly one maturity annotation. IOF constructs may include a maturity annotation.
natural language definition
definition written in plain text for human understanding
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 is required and will satisfy the role of a natural language definition. - It is optional, but recommended, for relations when the intent of a relation may be misunderstood. - There should be at most one. - This 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: a) 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' b) Classes – For classes whose label has multiple distinct terms, e.g, ManufacturingOperationSpecification, separate the terms but bound them with apostrophe marks: 'Manufacturing Operation Specification'.
primitive rationale
reason why necessary and sufficient conditions could not be provided
When 'is primitive' is set to true, a value for 'primitive rationale' must be provided. The rationale should indicate what is missing if additional work is required to define necessary and sufficient conditions.
replaced by
reference to the IRI of the target of a deprecated construct
The value of an iof-av:replacedBy annotation must be the IRI which replaces the target construct.
semi-formal natural language axiom
logic axiom expressed in natural language
Semi-formal natural language axioms MAY be provided if the term is primitive (is primitive is true). A construct MAY include more than one semi-formal natural language axiom annotation.
semi-formal natural language definition
logic definition that expresses a first order logic definition or common logic definition in natural language
This annotation is required if an element in an IOF OWL ontology has a First Order Logic definition or in a IOF Common Logic (where the element is defined using Common Logic). - The intent of this annotation to provide a transition or bridge from the First Order Logic definition of a notion to the natural language definition. This definition is intended to help a user understand the intended interpretation of the notion. - 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 has or bears.
definition of the term expressed in natural language that has the minimal usage of ontological terms and is intended to be a self-standing explanation
Usage of this annotation is optional but is recommended in cases where: - the natural language definition or elucidation rely heavily on the terms defined in the ontology - there exists an explanation of the term that is more familiar to SMEs that does not coincide with the definition present in the ontology
symbol
abbreviation that is a design, mark, or charaters(s) used conventionally to represent something, such as currency, quantity, or variable in an expression
Chemical Symbols: H, O, Mg Units of Measure: Km, Kg, G
synonym
alternative label (designation) used for the resource in some community
usage note
note that provides information about how a given notion or resource is used in the ontology's context