Final Review Cycle of the IOF Core

Owned by Chris Will
Last updated: 2022-02-18
11 min read

The intent of this page is to provide instructions that will facilitate the “final review cycle” of the IOF Core, which is a necessary step as we drive towards releasing a first version of what we might call an ontology and the IOF’s efforts so far. Before we begin and as we’ve recently seen a number of new members join the effort, it might be prudent to first give a brief overview on the current state of the core and where we are from a “software life cycle” perspective. Once that is out of the way, we’ll give instructions on how to access the IOF Core content and how to get involved in the review. Content is as follows:

Background & Current State of the IOF Core

For a cursory glance into the evolution of the IOF Core (formerly referred to as the “top-20 terms,” and later often the “top-26 terms”), we reflect back to a list of industrial domain terms that were submitted by IOF members years ago and from which we selected the top 20 to do a “prototype effort” – that of agreeing on natural language definitions and of mapping the terms to various three foundational ontologies: the Process Specification Language, the Basic Formal Ontology and DOLCE. Ultimately, we voted on and chose the Basic Formal Ontology or BFO. The prototype effort also resulted in the introduction of dozens of additional “mid-level” terms that mapped the top-20 terms to BFO. The effort resulted in an initial set of both natural language definitions and first order logic formalizations (FOL) for the terms and a paper that was published in 2019. Please note that where we use the word “term” herein or in other IOF discussions, we refer to both classes and object properties from an OWL perspective, or to entities and binary or higher-place relations from a logician’s perspective. For additional background information, please follow any of the following links to files that still reside on a Google Drive share folder (please note that these and other archival content will soon be migrated to the Atlassian portal):

Then in December of 2019, the management of term definitions and issues transitioned from Google documents to Protégé, and with our recent merger into OAGi, the management of issues and the keeping of minutes will transition to the Atlassian toolset as this review cycle gets underway.

In its current state, the IOF Core is a collection of 27 terms that are principally applicable to the industrial domains, and another 50 “mid-level” terms that we have either adopted with minor modifications from other mid-level ontologies, or have introduced ourselves. Additionally, we import and make use of 19 terms from the Common Core Ontology and another 9 from the Relations Ontology, which we utilize as they are currently defined. It should be noted however that the definitions of imported terms usually lack formalization in first order logic or are lacking in their OWL formalization –issues we intend to resolve in the future through closer collaboration with the respective organizations managing these ontologies.

On the surface or on a net-change basis, the number of terms in the IOF Core today is roughly on par with the number it had in 2019 – making it seem as though little progress has been made. In fact only a few new terms have been introduced while a number have been deprecated or have been moved to one of the domain ontology working groups, if we concluded a term was not likely to appear across multiple domains. The major changes since 2019 are in the definitional content of terms remaining in the core, not only to resolve outstanding issues raised in previously, but to expand or further constrain them to include complement examples, or exclude counter examples. And since few would disagree with the statement that 99% of our discussions are spent debating the natural language or semi-formal definitions of a term, and only about 1% on the FOL or the OWL axiomatization, we have deferred the effort of writing out of FOL or the OWL axiomatization until after agreement is reached on the former definitional content (and the elucidations for terms that are primitives). Reaching agreement on these term definitions so that we can formalize them, is a key objective of this final review cycle.

Where We Are From an Overall Development Lifecycle Perspective?

As far as the final review cycle and where it fits in the overall scheme of a traditional software development life cycle – of which ontological development efforts are surely close cousins – we realistically are still somewhere in the development phase. We can argue the case that we “froze scope” years ago by limiting the number of terms to the top-26 we selected, and the additional ones we’ve introduced along the way, but does our current scope constitute what one might call a “minimally-viable” set of terms from which practitioners in industry can be productive in building application ontologies, or domain-specific ontologies? As recently as a month ago, several of the working groups voiced concern that we should not release anything without at least provisional definitions for notions like event and state (stasis). In any case, we are in a final review cycle and although we will surely be adding some additional terms, we will make every attempt to reach a compromise between expanding scope further and driving towards a release. To that end, and to optimize our time, we will attempt to conduct the final review cycle in an “off-line mode” and utilize our weekly meetings to review issues that are raised, and ways towards resolving them, and minimize lengthy debates on the definitions themselves.

Referring then to the figure below, the golden box shows the current review cycle in the context of an overall software development life cycle. For convenience purposes, we are only showing the predecessor activity of “Term Analysis Procedure,” versus earlier activities like planning a release. The latest refresh of the IOF Core is the primary input to the Final Review Procedure and includes what we hope is a “stable” natural language definition for each term, and a stable semi-formal definition (for terms with both necessary and sufficient conditions or stable elucidations for terms that are deemed to be primative). In a few cases, a term will have a formalized definition in first order logic (FOL), and in even fewer cases, a term has been axiomatized in OWL. As mentioned earlier, a key objective of the final review cycle is to drive the definitional content of terms to the “fully-formalized” state, or what we might call a state of completion per the IOF technical principles and ontology annotation rules. And completion means, ideally, a term has no major outstanding issues, or if it does, we would expect to mention these the release notes. As far as details of what constitutes a release (Release Criteria) and the activities during the release cycle, this is a work-in-progress. If you wish to participate, feel free to join the Release Management Working Group.

Now to manage and track our progress throughout this review cycle, we have assigned a “level of maturity” to each term, which reflects the evolution of a term’s analysis and definitional content, the level of acceptance or review performed, and the number of pending open issues raised. For this measure, we have assigned one of four possible maturity levels as discussed in more detail below. We have not run an overall report to see what the overall status is as of today, but it is fair to say that most terms are in need of peer review and approval.

Where to Get Latest IOF Core?

The IOF Core is now managed through a private GitHub repository that we’ve established here. The IOF Core “ontology file” has been serialized into a standardized format that will facilitate the tracking of changes going forward. We have utilized a tool courtesy of the FIBO organization called “the serializer.” Presently, the IOF Core file has only been serialized in the rdf/xml syntax but once the review process gets further underway, we’ll be uploading serialized versions in other popular formats such as Turtle.  

Important Points About IOF Core Content

  • The IOF Core imports several ontologies and one meta file. These are located in the “imports” subfolder of the project files and include the following:

    • BFO-2020.owl – this is the first ISO released version of the BFO, released in 2020 (henceforth, BFO-2020). The import version the IOF has voted to use, is the the “temporalized version” of BFO-2020. The arguments for why we made this decision is beyond the scope of this discussion.

    • cco-imports.owl –mid-level or domain independent terms the IOF has imported and used from the Common Core Ontology, or CCO. We have extensively utilized the CCO in order to either map an industry domain term to BFO, or to introduce “hook” classes/relations that are generic or domain independent mid-level terms, under which we anticipate asserting additional industry-level terms using the “is-a” relation in the near future. An example would our use of the mid-level term “Artifact” from CCO, to assert any number of “man-made” objects such as machines, tools, piece of equipment, and so forth. We have of course sometimes renamed a CCO term label, as in the case of Artifact, which was relabeled Material Artifact.

    • ro-imports.owl – mid-level or domain independent terms the IOF has imported and used from the Relations Ontology, in order to either map an industry term to BFO, or to introduce “hook” classes/relations that are somewhat generic or abstract, with the understanding that many additional industry terms will be introduced as sibling classes in the future.

    • IOF_AnnotationsVocabulary.rdf – the definitional content for each term in the Core ontology is embodied in a set of annotation properties the IOF has adopted. We have established various rules on how these annotation properties are to be used. These are documented within the annotations file, under the description property for each.

  • Throughout the development and review phase of the IOF Core terms, we have introduced and utilized several “temporary” annotation properties to (a) manage the evolution of a term’s definitional content from its initial introduction, through the analysis phase, and to where it is fully formalized in accordance with the IOF’s Technical Principles guide, (b) facilitate the generation of supplementary release documentation at the term-level, and (c) document open action items, issues, arguments for changes made in a definition, and potential considerations for improving a definition in future releases – issues and action items we will soon migrate to the Atlassian Jira project. Please note that all temporary annotation properties will be removed in the released version of the IOF Core. To separate temporary annotations from the list of required or pro-forma annotation properties, we have prefixed the former with the letter ‘x’. The temporary annotation properties are as follows:

    • xDefinitionOtherCommon

    • xExampleComplement

    • xExampleCounter

    • xIssuesAndActionItems

    • xMaturity

For usage explanations of these properties, please read the description for each property provided in the core ontology file.

  • One of the temporary annotation properties is worthy of further note here, namely xMaturity. We will use this property to track the evolution of a term’s definitional content from the (continuing) analysis stage, to the fully-formalized stage. Each term appearing in the IOF Core file has been tagged as to its current status, and will be updated as it is further formalized and accepted according to our annotation rules and technical principles. Four maturity designations are used for this purpose:

    • Formalized → term has been analyzed, defined and formalized according to the IOF Technical Principles Guide and the Annotation Property Rules; term has been “peer-reviewed” by WG members with no major issues are outstanding

    • Stable Definition → term has been analyzed and a natural language definition has been identified and adopted by WG members; term however may be lacking in further formalization and may contain terms or notions to be analyzed, defined and added to the ontology

    • In Analysis → term or notion is under analysis by the WG, or has a candidate definition that has not yet been peer-reviewed

    • Pre-analysis → a new term or notion motivated by WG discussions, or one that needs to be introduced because it is contained in the definition of another term that has been adopted; although the analysis for such a term remains to be conducted, it will usually have a candidate natural language definition originating from the context where it is used, or from some external source

Raising Issues & Issue Resolution

For issues, questions or concerns related to a term – please create an issue in Jira under the IOF Core project. We’ve created a Jira “Epic” to group all term-level issues that are raised, and it is titled “Term Issues.” The URI is https://oagiscore.atlassian.net/browse/CW-3?atlOrigin=eyJpIjoiNzJjOWUxM2U1MTNlNDRiZmJiYjRlYjI5MTEyZGQ5MzgiLCJwIjoiaiJ9. Depending on the participation level – meaning how many issues get raised – we may create additional Jira Epics around “term clusters,” or in the worst-case, an epic for each term. In the meantime, go ahead and start your review and raise any issues you find. We will move the issues around as necessary and add structure along the way.

Of course, following the Barry Smith rule, if you find an issue, feel free to propose a work-around, or better yet, a “solution.” That will certainly speed up the review cycle and the resolution of term issues. Bear in mind though, that for any term where the intent is to formalize the definition with necessary and sufficient conditions, any solution you provide needs to consider the impact to/of any of the embedded terms. If your solution introduces new terms that don’t exist in the ontology, you are advised to provide provisional definitions for those as well.

For other issues not related specifically to a term or term’s definitional content – as in example issues you may have with the Atlassian toolset, GitHub, or the Final Review Procedure, and so forth – please raise those here: https://oagiscore.atlassian.net/browse/CW-5?atlOrigin=eyJpIjoiOTEwNDNkYmYzNjMxNGZjNzgyNjE3Y2YyNjg3NTk0N2MiLCJwIjoiaiJ9

Please note that at this time, GitHub will not and must not be used to raise issues. This is something we will defer until after we release a version of the IOF Core to a public. At that time, we most certainly will have to entertain the use of GitHub to raise and resolve issues raised by external users.

Getting Started & Call to Action

  • If you are reading this page, you’ve already been assigned a user account in the Atlassian toolset, so you have already completed the first step!

  • Next, download the Core ontology project code from GitHub to your local desktop. You will need an “invite” from GitHub to get access to this and any of the other IOF repositories that have been uploaded there. If you don’t have an invite, please email Chris.will@outlook.com or Will and provide your GitHub user ID. We’ll get you setup within about 24 hours.

NOTE: If you would like to have a copy of the IOF Core terms to review in a spreadsheet format, please send a request to chris.will@Outlook.com

  • If you haven’t already done so, please familiarize yourself on these annotation properties and rules by reading here.

  • Load up the Core ontology in your favorite ontology editor. Protégé is likely still the IOF standard for this at the present time.

  • Once you’ve loaded the ontology into your editor, the call to action is for you to start reviewing term definitions and formalizations. Raise issues and questions as mentioned above.

Of Special Mention

Although all IOF members are invited to participate in the final review cycle, to ensure we a sufficient level of review of each term, the working group chairs will be asked to explicitly confirm that they have reviewed and approve each term’s definitional content. This approval is needed initially regarding the natural language and semi-formal definitions or elucidations, and subsequently for the FOL and OWL axiomatization. The IOF Core working group meetings will be the venue during which such “explicit confirmation” will be requested, and recorded.

 

https://oagi.org/pages/connect-membership