BNOP - BORO™ Native Objects (Python)

BNOP is a comprehensive ontology library implementing the BORO (Business Object Reference Ontology) approach to information modeling in Python. This library provides a robust framework for creating, managing, and serializing ontological objects and their relationships.

Overview

BNOP is a reference implementation containing the code for the BORO Native Objects (Python) Domain. This is a fork of the original BNOP library created by BORO Solutions, adapted for use within the bCLEARer™ Pipeline Development Kit (PDK).

BORO is a foundational ontology that provides a rigorous top-level structure for information modeling. It uses a 4D (four-dimensional) perspective where objects persist through time and have temporal parts.

Library Structure

The BNOP library is organized into several key components:

1. Core Object Model

Located in /bnop/core/object_model/, this module contains the fundamental BNOP object classes:

• BnopObjects: The base class for all BNOP entities, maintaining registries of objects keyed by UUID and type
• BnopTypes: Represents ontological types that can classify instances
• BnopNames: Implements naming concepts for objects
• BnopTuples: Represents relationships between objects (e.g., type-instance, supertype-subtype)
• BnopElements: Basic elements in the ontology
• BnopPlaceableTypes: Types that can be placed in specific positions in tuples
• BnopTypePlaces: Defines positions in tuples for specific types

Each object maintains its relationships with other objects through sets like types, instances, supertypes, subtypes, etc.

2. Factory Classes

Located in /bnop/core/factories/, these classes provide methods for creating different types of BNOP objects:

• BnopObjectFactories: Creates basic objects
• BnopTypeFactories: Creates type objects
• BnopNameFactories: Creates name objects
• BnopTupleFactories: Creates relationship tuples
• BnopElementFactories: Creates elements
• BnopPlaceableTypeFactories: Creates placeable types
• BnopTypePlaceFactories: Creates type places

The factory pattern ensures consistent object creation with proper registration in the object registries.

3. Infrastructure

Located in /bnop/infrastructure/, this module provides utility classes:

• names.py: Utilities for working with names
• translators.py: Translators between different representations

4. Input/Output

Located in /bnop/bnop_io/, this module handles persistence of BNOP objects:

• shelve_bnop.py: Provides functions to save and load BNOP objects using Python's shelve module

5. Migrations

Located in /bnop/migrations/, this module includes functionality for format conversions:

• bnop_to_xml_migration: Contains classes to convert BNOP objects to XML representation
  • bnop_xml_write_orchestrator.py: Orchestrates the XML export process
  • adders: Contains classes that add specific object types to XML
  • sorters: Sorts objects for consistent XML output

6. Facades

The BnopFacades class (/bnop/bnop_facades.py) provides a simplified interface for common operations:

• Creating various types of BNOP objects (objects, types, names, tuples, etc.)
• Establishing relationships between objects
• Serializing BNOP objects to XML

Basic Usage

Creating Objects and Types

from bnop.bnop_facades import BnopFacades
from bclearer_orchestration_services.identification_services.uuid_service.uuid_helpers.uuid_factory import create_new_uuid

# Create repository UUID
repository_uuid = create_new_uuid()

# Create a simple object
object_uuid = create_new_uuid()
my_object = BnopFacades.create_bnop_object(
    object_uuid,
    repository_uuid,
    presentation_name="Example Object"
)

# Create a type
type_uuid = create_new_uuid()
my_type = BnopFacades.create_bnop_type(
    type_uuid,
    repository_uuid,
    presentation_name="Example Type"
)

# Create a name
name_uuid = create_new_uuid()
my_name = BnopFacades.create_bnop_name(
    name_uuid,
    "ExampleName",
    repository_uuid
)

Creating Relationships

from bclearer_core.ckids.boro_object_ckids import BoroObjectCkIds

# Create a type-instance relationship
type_instance_tuple = BnopFacades.create_bnop_tuple_from_two_placed_objects(
    create_new_uuid(),
    my_type,             # Type at place 1
    my_object,           # Instance at place 2
    BoroObjectCkIds.TypesInstances,
    repository_uuid
)

# Create a naming relationship
naming_tuple = BnopFacades.create_bnop_tuple_from_two_placed_objects(
    create_new_uuid(),
    my_name,             # Name at place 1
    my_object,           # Named object at place 2
    BoroObjectCkIds.NamedBy,
    repository_uuid
)

# Create a supertype-subtype relationship
supertype_tuple = BnopFacades.create_bnop_tuple_from_two_placed_objects(
    create_new_uuid(),
    my_type,             # Supertype at place 1
    another_type,        # Subtype at place 2
    BoroObjectCkIds.SuperSubTypes,
    repository_uuid
)

Persistent Storage

# Export to XML
BnopFacades.write_bnop_object_to_xml("output.xml")

# Using shelve for persistence
from bnop.bnop_io.shelve_bnop import write_bnop, read_bnop

# Save objects
write_bnop("bnop_data")

# Load and view objects
read_bnop("bnop_data")

Key Concepts

Object Registry

BNOP maintains two global registries:

• BnopObjects.registry_keyed_on_uuid: All objects indexed by UUID
• BnopObjects.registry_keyed_on_ckid_type: Objects indexed by their BORO classification

Naming and Identity

• Every BNOP object has a UUID for identity
• Objects can be associated with names via NamedBy relationships
• Names are themselves objects with exemplar representations (the text value)

Tuples and Relationships

Tuples represent relationships between objects:

• TypesInstances: Relates types to their instances
• SuperSubTypes: Establishes type hierarchies
• NamedBy: Connects names to the objects they name

Placeable Types and Type Places

BNOP supports complex relationship modeling through:

• Placeable types that can occupy positions in tuples
• Type places that define which types can go in which positions

Documentation Policy

Following the BORO documentation policy and principles from Robert C. Martin's "Clean Code," this library aims to be self-documenting through clean, expressive code.

Execution

This code is intended to be used as a library rather than run standalone.

Contributing

Issues and feedback are welcome. Code pull requests are not being accepted yet, so please raise anything you find as an issue rather than as a patch.

For anything that does not fit an issue, contact support@ontoledgy.io.

Licence

This project is licensed under the GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later). See the LICENSE.md file for the full text.

Commercial licences are available for organisations that cannot comply with the AGPL's network-use and source-disclosure terms. Contact support@ontoledgy.io for details.

Acknowledgements

This work was developed initially by BORO Solutions (https://www.borosolutions.net/) and was updated as part of the Information Management Framework to support the National Digital Twin programme, and funded by Department for Business, Energy & Industrial Strategy through the Centre for the Protection of National Infrastructure. It is being used here as the core upper ontology in the OntoLedgy bCLEARer PDK.