CleverRDFlib/docs/owl_extensions.md

OWL Extensions and Validation

CleverRDFLib provides comprehensive support for OWL (Web Ontology Language) extensions, including validation, consistency checking, metadata extraction, and version management.

OWL Validation

The framework includes built-in OWL validation to detect errors and warnings in your ontologies.

Accessing Validation Results

Validation is performed automatically when validate_on_load=True (the default):

from cleverrdf_lib import OntologyLoader

loader = OntologyLoader(validate_on_load=True)
result = loader.load_ontology("ontology.ttl")

# Access validation result
validation_result = result.owl_validation_result

# Check if validation passed
if validation_result.is_valid:
    print("Ontology is valid!")
else:
    print("Validation errors found:")
    for error in validation_result.errors:
        print(f"  - {error}")
    
    print("Validation warnings:")
    for warning in validation_result.warnings:
        print(f"  - {warning}")

Validation Result Structure

The OWLValidationResult object provides:

• is_valid: Boolean indicating if the ontology is valid
• errors: List of validation error messages
• warnings: List of validation warning messages

Disabling Validation

To skip validation for faster loading:

loader = OntologyLoader(validate_on_load=False)
result = loader.load_ontology("ontology.ttl")

# Validation result will still be available but won't be computed until accessed
validation_result = result.owl_validation_result  # Lazy evaluation

Consistency Checking

Consistency checking verifies that the ontology is logically consistent (no contradictions):

from cleverrdf_lib import OntologyLoader

loader = OntologyLoader()
result = loader.load_ontology("ontology.ttl")

# Access consistency result
consistency_result = result.owl_consistency_result

# Check consistency status
if consistency_result.is_consistent:
    print("Ontology is consistent!")
else:
    print("Consistency issues found:")
    for issue in consistency_result.issues:
        print(f"  - {issue.message}")
        print(f"    Element: {issue.element_iri}")
        print(f"    Type: {issue.issue_type}")

Consistency Issue Structure

Each consistency issue contains:

• message: Human-readable description of the issue
• element_iri: IRI of the element with the issue
• issue_type: Type of consistency issue (e.g., "circular", "disjoint")

Common Consistency Issues

• Circular class definitions: Classes that reference each other in a cycle
• Conflicting disjointness: Classes declared as both disjoint and overlapping
• Missing domain/range: Properties without proper domain or range definitions

Metadata Extraction

Extract OWL ontology metadata including version information and compatibility statements:

from cleverrdf_lib import OntologyLoader

loader = OntologyLoader()
result = loader.load_ontology("ontology.ttl")

# Access metadata
metadata = result.owl_metadata

# Access specific metadata fields
print(f"Version IRI: {metadata.get('version_iri')}")
print(f"Prior Version: {metadata.get('prior_version')}")
print(f"Backward Compatible With: {metadata.get('backward_compatible_with')}")
print(f"Incompatible With: {metadata.get('incompatible_with')}")

Available Metadata Fields

The metadata dictionary includes:

• version_iri: The version IRI of the ontology
• prior_version: Previous version of the ontology
• backward_compatible_with: List of compatible versions
• incompatible_with: List of incompatible versions
• imports: List of imported ontology URIs
• labels: Ontology labels (rdfs:label)
• comments: Ontology comments (rdfs:comment)

Version Management

The framework provides version management capabilities for tracking ontology versions:

from cleverrdf_lib import OntologyLoader

loader = OntologyLoader()
result = loader.load_ontology("ontology.ttl")

# Access version manager
version_manager = result.owl_version_manager

# Extract version information
version_info = version_manager.extract_version_info()
print(f"Version IRI: {version_info.version_iri}")
print(f"Version: {version_info.version_info}")

# Extract version relationships
relationships = version_manager.extract_relationships()
for rel in relationships:
    print(f"Relationship: {rel.relationship_type}")
    print(f"  Target: {rel.target_version}")

Version Information

The OntologyVersion object provides:

• version_iri: The version IRI
• version_info: Version string (owl:versionInfo)
• ontology_iri: The ontology IRI

Version Relationships

Version relationships describe how versions relate to each other:

• relationship_type: Type of relationship (e.g., "backward_compatible_with", "incompatible_with")
• target_version: The target version IRI

OWL-Specific Class Hierarchy Features

The class hierarchy supports OWL-specific features:

Object Properties

Object properties link classes to other classes:

from cleverrdf_lib import OntologyLoader

loader = OntologyLoader()
result = loader.load_ontology("ontology.ttl")
hierarchy = result.class_hierarchy

# Get all classes (iterate over dictionary values)
for class_node in hierarchy.get_all_classes().values():
    # Access object properties where this class is the domain
    for prop in class_node.object_properties_as_domain.values():
        print(f"Property: {prop.iri}")
        print(f"  Domain: {prop.domain.iri if prop.domain else 'None'}")
        print(f"  Range: {prop.range.iri if prop.range else 'None'}")
    
    # Access object properties where this class is the range
    for prop in class_node.object_properties_as_range.values():
        print(f"Property: {prop.iri} (range)")

Datatype Properties

Datatype properties link classes to datatypes:

from cleverrdf_lib import OntologyLoader

loader = OntologyLoader()
result = loader.load_ontology("ontology.ttl")
hierarchy = result.class_hierarchy

# Iterate over dictionary values
for class_node in hierarchy.get_all_classes().values():
    # Access datatype properties
    for prop in class_node.datatype_properties_as_domain.values():
        print(f"Datatype Property: {prop.iri}")
        print(f"  Domain: {prop.domain.iri if prop.domain else 'None'}")
        print(f"  Range: {prop.range.iri if prop.range else 'None'}")

Property Types

Properties have types that can be queried:

from cleverrdf_lib.core.class_hierarchy import PropertyType

# Iterate over dictionary values
for prop in hierarchy.get_all_properties().values():
    if prop.ptype == PropertyType.Object:
        print(f"Object Property: {prop.iri}")
    elif prop.ptype == PropertyType.DataType:
        print(f"Datatype Property: {prop.iri}")
    else:
        print(f"Other Property: {prop.iri}")

Advanced OWL Features

Custom Validators

You can extend the validation system with custom validators:

from cleverrdf_lib.owl.validator import OWLValidator

class CustomOWLValidator(OWLValidator):
    """Custom validator with additional checks."""
    
    def validate(self):
        # Call parent validation
        result = super().validate()
        
        # Add custom validation
        custom_errors = self._check_custom_rules()
        result.errors.extend(custom_errors)
        
        return result
    
    def _check_custom_rules(self):
        # Implement custom validation logic
        return []

Consistency Checker Extension

Extend the consistency checker for domain-specific checks:

from cleverrdf_lib.owl.consistency_checker import ConsistencyChecker

class CustomConsistencyChecker(ConsistencyChecker):
    """Custom consistency checker."""
    
    def check_consistency(self):
        # Call parent checking
        result = super().check_consistency()
        
        # Add custom checks
        custom_issues = self._check_custom_consistency()
        result.issues.extend(custom_issues)
        
        return result
    
    def _check_custom_consistency(self):
        # Implement custom consistency checks
        return []

Best Practices

1. Enable validation: Always validate ontologies in development
2. Check consistency: Verify consistency before using ontologies in production
3. Review metadata: Check version information and compatibility statements
4. Handle warnings: Address validation warnings to improve ontology quality
5. Use version management: Track ontology versions for compatibility

Next Steps

• Learn about Class Hierarchy Navigation
• Explore Loading Result API
• Understand Resolvers