CleverRDFlib/docs/index.md

CleverRDFLib Framework Documentation

Introduction

CleverRDFLib is a Python framework designed to facilitate object-oriented access to ontology class hierarchies and their descriptions. The framework provides a high-level, navigable object model that allows developers to work with RDF/OWL ontologies without the need to write SPARQL queries or directly manipulate RDF triples.

Purpose

The primary purpose of CleverRDFLib is to:

• Simplify ontology access: Provide intuitive, object-oriented navigation from classes to their children, parents, and associated properties
• Eliminate SPARQL complexity: Enable developers to work with ontologies without writing SPARQL queries
• Support extensibility: Allow easy extension through custom handlers, resolvers, filters, and converters
• Handle RDFS and OWL: Support both RDFS (RDF Schema) and OWL (Web Ontology Language) extensions
• Enable custom repositories: Facilitate fetching ontology files from custom repositories by writing custom Chain of Responsibility handlers

Key Features

• Object-Oriented Navigation: Navigate class hierarchies using intuitive object properties (e.g., class_node.parents, class_node.children, class_node.object_properties_as_domain)
• Recursive Reference Resolution: Automatically resolve and load referenced ontologies (owl:imports, rdfs:seeAlso, etc.)
• Multiple Loading Strategies: Support for depth-first and breadth-first loading strategies
• Extensible Architecture: Easily extend the framework with custom resolvers, filters, handlers, and converters
• OWL Validation: Built-in OWL validation and consistency checking
• Observer Pattern: Monitor loading and build events through observer interfaces
• Format Conversion: Convert class hierarchies to custom object representations using the Visitor pattern
• IRI Filtering: Filter IRIs to exclude local or standard namespaces that are not known a priori

Architecture Overview

CleverRDFLib follows advanced object-oriented design principles and extensively uses design patterns:

• Factory/AbstractFactory: For creating resolvers and strategies
• Chain of Responsibility: For handling different reference types and graph loading
• Strategy: For different loading strategies (depth-first, breadth-first)
• Builder: For constructing class hierarchies
• Visitor: For graph traversal and conversion
• Observer: For event notifications
• Facade: For providing a simple interface to complex subsystems

Design Principles

The framework adheres to SOLID principles:

• Single Responsibility: Each class has a single, well-defined purpose
• Open/Closed: Extensible through interfaces and abstract classes without modifying existing code
• Liskov Substitution: Subtypes are substitutable for their base types
• Interface Segregation: Interfaces are focused and specific
• Dependency Inversion: Dependencies on abstractions, not concrete implementations

Quick Start

from cleverrdf_lib import OntologyLoader, LoadingResult

# Create a loader with default configuration
loader = OntologyLoader()

# Load an ontology from a local file
result: LoadingResult = loader.load_ontology("path/to/ontology.ttl")

# Verify loading was successful
if not result.is_successful_for_main_ontology:
    raise RuntimeError(f"Failed to load ontology. Errors: {result.errors}")

# Verify that at least one ontology was loaded
if result.loaded_count == 0:
    raise RuntimeError("No ontologies were loaded. Check the file path and format.")

# Access the class hierarchy
hierarchy = result.class_hierarchy

# Navigate the hierarchy
for class_node in hierarchy.get_all_classes_as_list():
    print(f"Class: {class_node.iri}")
    print(f"  Parents: {[p.iri for p in class_node.parents]}")
    print(f"  Children: {[c.iri for c in class_node.children]}")
    print(f"  Object Properties: {[p.iri for p in class_node.object_properties_as_domain.values()]}")

Documentation Structure

This documentation is organized into the following sections:

1. Basic Usage: Loading ontologies from local files and web URLs
2. Error Detection and Handling: Understanding and handling errors during loading
3. OWL Extensions and Validation: OWL-specific features and validation API
4. Resolvers: Reference resolvers and how to extend them
5. Class Hierarchy Navigation: Building and navigating class hierarchies
6. IRI Filters: Filtering IRIs to exclude namespaces
7. Loading Result API: Accessing loading results and metadata
8. Class Hierarchy Conversion: Converting hierarchies to custom formats
9. Observers API: Monitoring loading and build events