Version History

Contents

Overview

IOF Ontologies require consistent policies for guidance on where new concepts are defined, how modules are structured, and how shared terminology evolves. This document provides those guidelines.

It lays out how to create, split, or elevate ontology modules so that each module remains focused, reusable, and easy to maintain. It explains how to place new terms where they belong, avoid duplication, and ensure that content intended for broad use is positioned to be shared across projects and organizations. The document also provides methods for safely refactoring existing ontology constructs to support reuse while preserving the meaning required for regulated biopharmaceutical workflows.

When these guidelines are followed, the result is a modular, coherent ontology structure that reduces rework, improves integration, increases clarity for contributors, and supports scalable reuse across the IOF ecosystem. This enables organizations to align data and knowledge resources more efficiently and to collaborate more effectively across systems, suppliers, and regulatory environments.

See https://oagi.atlassian.net/wiki/x/AQB_ggE on module and ontology naming policies.

Mission and Objectives

The primary objective is to define clear, repeatable guidelines to ensure that new and existing IOF ontology constructs are placed and connected appropriately within the IOF framework. To accomplish these aims, it will:

• Define principles and procedures for creating IOF reference ontology modules aligned with IOF architectural standards.

• Provide criteria and guidance for determining:

  • connections among modules to ensure coherence and maintainability; and

  • placement of new and existing constructs within the IOF structure.

• Establish a structured governance process to be maintained by the IOF Architecture Working Group.

Definitions

For the purposes of this document, the following terms and definitions apply. Where a term is cited from an external source, the source is indicated.

[These terms will be sorted later.]

IRI

Ontology

Realist Ontology

OWL Ontology

OWL Ontology Module

OWL Ontology Construct

Ontology Construct Definition

Module Creation and Evolution Guidelines

This section provides guidance for determining when to create a new BMIC ontology module, when to split an existing one, and when to promote a module or its contents for broader reuse within the IOF framework. The goal is to maintain coherence, minimize redundancy, and ensure that module boundaries reflect genuine conceptual distinctions rather than project or organizational convenience.

When creating a new module, all applicable normative ontology-development policies beneath https://oagi.atlassian.net/wiki/x/LQCA1g must be followed, such as:

• https://oagi.atlassian.net/wiki/x/AYBzYwE, which specifies the format for all ontology module IRIs, construct IRIs, annotation IRIs, and individual IRIs

• https://oagi.atlassian.net/wiki/x/AQDMQwE, which is a comprehensive policy for which annotations should or must be present, and how to use them

• https://oagi.atlassian.net/wiki/x/AYDnJgE, which is a comprehensive policy for how every ontology module must be serialized before committing to the IOF GitHub repository such that different versions can be compared (e.g., with git diff)

Creating a New Module

A new module should be created when:

• The proposed content represents a coherent, reusable set of constructs that form a natural conceptual unit. For example, the constructs called Batch Run, Recipe Creation Process, and Recipe all naturally belong in a module called Recipe.

• Its scope cannot be accommodated cleanly within any existing module without introducing overlap or tension.

• It provides domain content that can be maintained, versioned, and reused independently.

• Dependencies on other modules can be clearly defined and limited to having no circular dependencies.

Before creating a new module, contributors should verify that no existing IOF or BMIC module already covers the same conceptual ground and that the proposed scope aligns with the IOF architectural principles.

Splitting an Existing Module

A module should be split when:

• Its scope has grown to encompass two or more conceptually distinct areas that could evolve independently.

• Internal dependencies or constraints make maintenance difficult or introduce inconsistent modeling styles.

• A subset of its content has become sufficiently stable or reusable to warrant independent versioning or governance.

Splitting should preserve interoperability by establishing clear import relationships and maintaining a directed acyclic graph (DAG) of module dependencies.

Elevating a Module for Broader Reuse

Elevating refers to generalizing a module or its elements so they can serve broader use cases within the IOF. Promotion is appropriate when:

• The content captures patterns or constructs applicable across multiple domains.

• Its constructs have proven stable and well-understood through repeated use.

• The material can replace or subsume parallel constructs in other modules, reducing redundancy.

• The IOF Technical Oversight Board agrees that the content’s elevation improves modular structure and reuse.

Elevated modules or elements should be refactored to remove domain-specific constraints and reclassified under the appropriate IOF reference layer. (See https://oagi.atlassian.net/wiki/spaces/IOF/pages/6091145217/BMIC+Ontology+Construct+Placement+Guidelines#Construct-Refactoring, below.)

Governance and Documentation

All creation, split, and promotion actions should be:

• Accompanied by a short rationale describing scope, impact, and dependencies.

• Documented in the module’s metadata and tracked in the IOF repository for traceability.

Term Module Placement Guidelines

This section explains how to decide where new classes and properties (“terms”) belong within the ontology’s modular structure. The goal is to keep each module coherent, reusable, and understandable to both ontology engineers and domain experts, while minimizing unnecessary dependencies. These are guidelines, not binding policy.

Guiding Principles

• Clarity: Each module has one clear purpose that can be named without “and” or “or.”

• Cohesion: The terms in a module should belong together—they address the same topic, function, or pattern. If the contents feel unrelated, the module should be split.

• Coherence: The meaning of terms within a module should fit together logically and consistently—their definitions should not conflict or pull in different conceptual directions.

• Reuse before duplication: Use existing terms where possible rather than redefining them.

• Low coupling: Modules should rely only on the minimum other modules needed for their meaning. Avoid forcing users to import large modules to access a single term.

• Stability through ownership: Only the module that defines a term may change its meaning.

• Transparency: Non-normative shortcut modules may add convenience properties but must not modify normative content.

When to place a term in an existing module

When a single new term’s meaning depends on other classes or on properties used in its definition, place it in the same module as those classes and properties.

Exception. When you are introducing a cohesive family of interdependent subclasses, create a child module that imports the superclass’s module. Keep the family together where their differentiating properties and shared patterns are defined.

Example. Equipment lives in the Equipment module. A planned family {HydraulicPump, GearPump, DiaphragmPump} that shares properties like hasWorkingFluid and hasDisplacementProfile goes in a child Pump module that imports Equipment.

When to put a term into a new module

When a new term cannot be defined cleanly using only one existing module and its imports, create a new module. The new module should import the minimum number of other modules needed to define its terms. If the term’s placement feels forced or awkward, that’s a sign that module boundaries may need review. (See https://oagi.atlassian.net/wiki/spaces/IOF/pages/6091145217/BMIC+Ontology+Construct+Placement+Guidelines#Creating-a-New-Module, above.)

Example: If both the Equipment and Material modules are needed to define FilterMedium, a small Filtration module that imports those two may be clearer than adding FilterMedium to either.

When to reuse or reference a term from another module

When a term from another module already expresses the intended type, reuse it directly rather than duplicating it. If a more specific type is needed, define it as a subclass in your own module rather than modifying the imported definition.

Example: If the Manufacturing Processes module already defines AssemblyProcess as a subclass of Process, and you need to represent WeldingProcess as a specialized type of AssemblyProcess, define WeldingProcess as a subclass of AssemblyProcess in your own module. Do not edit AssemblyProcess itself.

When to extend another module’s content

When refinement is needed, limit extensions to weaker relations such as owl:subClassOf or owl:subPropertyOf. Do not redefine or replace imported classes or properties using owl:equivalentClass or owl:equivalentProperty.

If a missing necessary condition or property logically belongs in another module, raise it with that module’s maintainers so it can be promoted to a shared or higher-level module.

Example: If defining HydraulicPump requires a restriction on a property that logically belongs to FluidSystem, request that it be added there rather than locally.

When a term is widely reused

When a cluster of terms is expected to be reused across many modules, isolate it in a small, focused module to avoid forcing large imports. This keeps dependencies lightweight and reuse easy.

Example: the terms in the Certification module applies broadly across domains.

When naming or clustering feels awkward

When you cannot describe a module’s purpose with a single clear noun phrase—without “and” or “or”—the clustering is probably too broad. Reconsider the grouping before adding more terms.

Example: A module named Material and Equipment is likely doing too much. Separate them into Material and Equipment modules.

When considering “shortcut” modules

Shortcut properties (e.g., a convenience relation that elides that a person who was a participant in a birth event that occurred during a time interval via PersonBirthEventTimeIntervalStartTime) may be placed in non-normative modules that sit beneath normative ontologies. These modules may import normative ones but must not alter their logical definitions.

Such modules are optional and should be clearly labeled as non-normative.

When equivalence is appropriate

owl:equivalentClass and owl:equivalentPropertybetween two terms may only be used for mapping or alignment modules that connect an IOF ontology module to an external vocabulary or standard. This use is legitimate but currently out of scope for this document. However, owl:equivalentClass may be used between a term representing an owl:Class and a class expression (i.e., an anonymous construct including not, some, all, union, or intersection).