The following paragraphs and corresponding tables provide guidelines on metadata and related annotations to be used for the IDMP Project.

Dependencies on ontologies that are external to the Pistoia Alliance / IDMP project are given below.

Ontology Resource (Model Element) Labeling

The annotations for labels given below are primarily used with for the content of an ontology, although a label at the ontology level is also required.  See below for ontology-level metadata requirements.

Ontology Resource (Model Element) Definitions

Definitions are required for every class, property and nominal (individual that is key to understanding the ontology, rather than generated reference data or example data) in an IDMP ontology.  In cases where a definition does not make sense, such as for generated code lists, a description, using dct:description, is often helpful to users. 

Definitions for the IDMP project should generally follow the guidance provided in

• ISO 704: Terminology work — Principles and methods for terminology development,
• ISO 1087: Terminology work and terminology science — Vocabulary.

In other words, the following minimal metadata is required for each class, property, and nominal:

• a label,
• a definition,
• explanatory and other notes, such as examples, as well as source information when applicable.

Definitions MUST follow ISO 704 recommendations for establishing good definitions.

We anticipate that many commercial and government organizations will use the IDMP ontologies as a reference for enterprise glossary development, interoperability, natural language processing, machine learning, and other applications that need both the mathematics and logic incorporated in the ontology as well as the terminology, which is essential for enterprise glossary work and natural language processing applications. We recommend and are using ISO 704 for IDMP primarily because the principles it defines help ensure the consistency and quality of our definitions:

• Every class, property, and individual (nominal) MUST have a skos:definition (exactly 1 per natural language, with the default being American English).
• Definitions MUST be ISO 704 conformant, meaning; they must be expressed as partial sentences that can be used to replace the ontology element (concept, relationship, attribute, nominal) in a sentence.
• Any additional clarification, scope notes, explanatory notes, or other comments on the use of a given concept should be incorporated in other annotations.
• Definitions MUST not be circular, i.e., the class, property, or individual name must not be used in the definition itself.

Additional requirements with respect to definition development and supporting annotations include:

• Every first-class element (class, property, and defining individual (nominal)) must have a definition, expressed using the skos:definition annotation property rather than rdfs:comment.
• ISO 704 suggests a "genus / differentia" structure for definitions, meaning, it recommends identifying one or more ancestral concepts as well as relationships and characteristics that differentiate the concept in question from sibling concepts.
  • E.g. A legal entity is a
    • (GENUS) legal person
    • (DIFFERENTIA SPECIFICA) that is a partnership, corporation, or other organization having the capacity to negotiate contracts, assume financial obligations, and pay off debts, organized under the laws of some jurisdiction
  • E.g. A debt instrument is a
    • (GENUS) financial instrument
    • (DIFFERENTIA SPECIFICA) that enables the issuing party to raise funds by accepting the obligation to repay a lender by a particular time in accordance with the terms of a contract
  • For classes (nouns), most definitions should be phrased <parent class>" that …", naming the parent(s) and including text that relates that class to others through relationships (object properties) and characteristics (attributes / data properties).
  • For properties, most definitions should be phrased <parent property>" that …" – in a similar form as the definitions for classes; all property definitions must begin with a verb.
• Definitions should not include content that is or can be modeled via restrictions unless that content is inherently required to define the concept. For example, a contract is defined as an agreement between competent parties (and other things).  Because the fact that at least two parties are required to define a contract, it is included in the intensional definition even though we also have a restriction on having at least two parties in FIBO. 
• Definitions ideally should be sourced from sanctioned references, such as government glossaries, ISO standards, etc. and such sources should be noted in annotations that specify their source (see below for annotations for references).
• Additional information, such as examples, scope details, explanations, and so forth, should be captured using the appropriate annotation from SKOS, Dublin Core, or the CMNS Annotation Vocabulary, where possible. If an additional annotation is required and not present in one of these vocabularies, it should be presented to the governance team for inclusion.
• Reference data individuals may use dct:description to provide something similar to a definition, if a formal definition is infeasible, but any defining individual (nominal) MUST use skos:definition as the annotation property linking that individual to its definition.

Citations and References

Several annotation properties are useful for referring to the source for terminology, definitions, additional details or other information about a resource.  For the purposes of IDMP, the following annotations may be used, as appropriate. We may investigate using a more complete ontology for bibliographic references if that becomes necessary over the course of the project.

Notes

A number of other annotations are useful for explaining the classes and properties in the IDMP ontology. We use a combination of Dublin Core Metadata Terms, Simple Knowledge Organization System (SKOS) annotations, and additional annotations defined in the Commons Annotation Vocabulary, as needed.  These include the following:

Licensing and Copyright Information

Every IDMP ontology MUST include exactly one (1) license statement and at least one copyright statement.  The license will be an open-source license as determined prior to release, likely either the MIT license or CC by 4 from Creative Commons.  FIBO and other OMG ontologies as well as the IOF ontologies use the MIT license based on feedback from corporate attorneys for the participating organizations who preferred it over CC by 4.  Thus, the MIT license is the default for the IDMP ontologies until / unless some other decision is reached by the board.

Change Management and Versioning

Every IDMP ontology MUST include a non-versioned and versioned ontology IRI, as specified in Internationalized Resource Identifier (IRI) Structure, Format, and Ontology Naming Conventions for IDMP.  For released ontologies, the ontology version IRI will include either a version <YYYYMMDD> or possibly follow the mechanism used in FIBO for quarterly releases, which is <QxYYYY>, as determined as we approach a final release for the MVP.  Released ontologies managed in GitHub will use the <YYYYMMDD> convention, however. Pre-release ontologies will include the owl:versionIRI annotation but the IRI will be the same as the non-versioned IRI until such time as the ontology is released. The following additional annotations are required or optional as described below.

Contributors

A number of organizations are participating in the IDMP effort.  We could include the names of the people that were creators / contributors to a given ontology as desired, though each company should have a copyright statement rather than duplicating company names as contributors.  The following annotations may be used for this purpose.