rdf-construct 0.2.0__py3-none-any.whl

rdf_construct/puml2rdf/validators.py

@@ -0,0 +1,451 @@
+"""Validation for PlantUML import.
+
+This module provides validation of parsed PlantUML models and
+generated RDF, ensuring consistency and flagging potential issues.
+"""
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Optional
+
+from rdflib import Graph, URIRef, RDF, RDFS
+from rdflib.namespace import OWL
+
+from rdf_construct.puml2rdf.model import PumlModel, PumlRelationship, RelationshipType
+
+
+class Severity(Enum):
+    """Severity level for validation issues."""
+
+    ERROR = "error"  # Must be fixed
+    WARNING = "warning"  # Should be reviewed
+    INFO = "info"  # Informational
+
+
+@dataclass
+class ValidationIssue:
+    """A validation issue found during checking.
+
+    Attributes:
+        severity: How serious the issue is
+        code: Machine-readable issue code
+        message: Human-readable description
+        entity: The entity this issue relates to
+        suggestion: Optional fix suggestion
+    """
+
+    severity: Severity
+    code: str
+    message: str
+    entity: Optional[str] = None
+    suggestion: Optional[str] = None
+
+    def __str__(self) -> str:
+        prefix = f"[{self.severity.value.upper()}]"
+        entity_str = f" ({self.entity})" if self.entity else ""
+        return f"{prefix} {self.code}: {self.message}{entity_str}"
+
+
+@dataclass
+class ValidationResult:
+    """Result of validation.
+
+    Attributes:
+        issues: List of validation issues found
+    """
+
+    issues: list[ValidationIssue]
+
+    @property
+    def has_errors(self) -> bool:
+        """Return True if any errors were found."""
+        return any(i.severity == Severity.ERROR for i in self.issues)
+
+    @property
+    def has_warnings(self) -> bool:
+        """Return True if any warnings were found."""
+        return any(i.severity == Severity.WARNING for i in self.issues)
+
+    @property
+    def error_count(self) -> int:
+        """Count of errors."""
+        return sum(1 for i in self.issues if i.severity == Severity.ERROR)
+
+    @property
+    def warning_count(self) -> int:
+        """Count of warnings."""
+        return sum(1 for i in self.issues if i.severity == Severity.WARNING)
+
+    def errors(self) -> list[ValidationIssue]:
+        """Return only error-level issues."""
+        return [i for i in self.issues if i.severity == Severity.ERROR]
+
+    def warnings(self) -> list[ValidationIssue]:
+        """Return only warning-level issues."""
+        return [i for i in self.issues if i.severity == Severity.WARNING]
+
+
+class PumlModelValidator:
+    """Validates parsed PlantUML models for consistency.
+
+    Checks include:
+    - Relationships reference existing classes
+    - No duplicate class names
+    - Attributes have valid types
+    - Inheritance doesn't create cycles
+    """
+
+    def validate(self, model: PumlModel) -> ValidationResult:
+        """Validate a parsed PlantUML model.
+
+        Args:
+            model: The parsed model to validate
+
+        Returns:
+            ValidationResult with any issues found
+        """
+        issues: list[ValidationIssue] = []
+
+        # Check for duplicate class names
+        issues.extend(self._check_duplicate_classes(model))
+
+        # Check relationship references
+        issues.extend(self._check_relationship_references(model))
+
+        # Check for inheritance cycles
+        issues.extend(self._check_inheritance_cycles(model))
+
+        # Check attribute types
+        issues.extend(self._check_attribute_types(model))
+
+        # Check for classes without any relationships
+        issues.extend(self._check_orphan_classes(model))
+
+        return ValidationResult(issues=issues)
+
+    def _check_duplicate_classes(self, model: PumlModel) -> list[ValidationIssue]:
+        """Check for duplicate class names."""
+        issues = []
+        seen = set()
+
+        for cls in model.classes:
+            if cls.name in seen:
+                issues.append(
+                    ValidationIssue(
+                        severity=Severity.ERROR,
+                        code="DUPLICATE_CLASS",
+                        message=f"Duplicate class name: {cls.name}",
+                        entity=cls.name,
+                        suggestion="Rename one of the classes or use packages to distinguish them",
+                    )
+                )
+            seen.add(cls.name)
+
+        return issues
+
+    def _check_relationship_references(self, model: PumlModel) -> list[ValidationIssue]:
+        """Check that relationships reference existing classes."""
+        issues = []
+
+        # Include both local and qualified names for lookup
+        class_names = set()
+        for cls in model.classes:
+            class_names.add(cls.name)  # Local name: "Building"
+            class_names.add(cls.qualified_name)  # Qualified: "building.Building"
+
+        for rel in model.relationships:
+            if rel.source not in class_names:
+                issues.append(
+                    ValidationIssue(
+                        severity=Severity.ERROR,
+                        code="UNKNOWN_CLASS",
+                        message=f"Relationship references unknown source class: {rel.source}",
+                        entity=rel.source,
+                        suggestion=f"Add class declaration for '{rel.source}'",
+                    )
+                )
+            if rel.target not in class_names:
+                issues.append(
+                    ValidationIssue(
+                        severity=Severity.ERROR,
+                        code="UNKNOWN_CLASS",
+                        message=f"Relationship references unknown target class: {rel.target}",
+                        entity=rel.target,
+                        suggestion=f"Add class declaration for '{rel.target}'",
+                    )
+                )
+
+        return issues
+
+    def _check_inheritance_cycles(self, model: PumlModel) -> list[ValidationIssue]:
+        """Check for cycles in inheritance hierarchy."""
+        issues = []
+
+        # Build inheritance graph
+        inheritance: dict[str, set[str]] = {}
+        for rel in model.inheritance_relationships():
+            if rel.source not in inheritance:
+                inheritance[rel.source] = set()
+            inheritance[rel.source].add(rel.target)
+
+        # Check for cycles using DFS
+        def has_cycle(start: str, visited: set[str], path: list[str]) -> Optional[list[str]]:
+            if start in path:
+                cycle_start = path.index(start)
+                return path[cycle_start:] + [start]
+
+            if start in visited:
+                return None
+
+            visited.add(start)
+            path.append(start)
+
+            for parent in inheritance.get(start, set()):
+                cycle = has_cycle(parent, visited, path)
+                if cycle:
+                    return cycle
+
+            path.pop()
+            return None
+
+        for cls in model.classes:
+            cycle = has_cycle(cls.name, set(), [])
+            if cycle:
+                issues.append(
+                    ValidationIssue(
+                        severity=Severity.ERROR,
+                        code="INHERITANCE_CYCLE",
+                        message=f"Inheritance cycle detected: {' -> '.join(cycle)}",
+                        entity=cls.name,
+                        suggestion="Break the cycle by removing one of the inheritance relationships",
+                    )
+                )
+                break  # Only report once
+
+        return issues
+
+    def _check_attribute_types(self, model: PumlModel) -> list[ValidationIssue]:
+        """Check that attribute types are recognized."""
+        issues = []
+
+        known_types = {
+            "string", "str", "text",
+            "integer", "int",
+            "decimal", "float", "double", "number",
+            "boolean", "bool",
+            "date", "datetime", "time",
+            "gYear", "gyear", "gYearMonth",
+            "duration",
+            "uri", "anyURI", "anyuri", "url",
+            "base64", "hexBinary",
+            "language", "token",
+        }
+
+        for cls in model.classes:
+            for attr in cls.attributes:
+                if attr.datatype and attr.datatype.lower() not in known_types:
+                    if not attr.datatype.startswith("xsd:"):
+                        issues.append(
+                            ValidationIssue(
+                                severity=Severity.WARNING,
+                                code="UNKNOWN_DATATYPE",
+                                message=f"Unknown datatype '{attr.datatype}' for attribute '{attr.name}'",
+                                entity=f"{cls.name}.{attr.name}",
+                                suggestion="Use standard XSD type or add custom mapping in config",
+                            )
+                        )
+
+        return issues
+
+    def _check_orphan_classes(self, model: PumlModel) -> list[ValidationIssue]:
+        """Check for classes with no relationships."""
+        issues = []
+
+        # Get all classes involved in relationships
+        related_classes = set()
+        for rel in model.relationships:
+            related_classes.add(rel.source)
+            related_classes.add(rel.target)
+
+        for cls in model.classes:
+            if cls.name not in related_classes and not cls.attributes:
+                issues.append(
+                    ValidationIssue(
+                        severity=Severity.INFO,
+                        code="ISOLATED_CLASS",
+                        message=f"Class '{cls.name}' has no relationships or attributes",
+                        entity=cls.name,
+                        suggestion="Consider adding relationships or attributes",
+                    )
+                )
+
+        return issues
+
+
+class RdfValidator:
+    """Validates generated RDF for OWL/RDFS consistency.
+
+    Checks include:
+    - Classes are typed as owl:Class
+    - Properties have domain and range
+    - No dangling references
+    """
+
+    def validate(self, graph: Graph) -> ValidationResult:
+        """Validate an RDF graph.
+
+        Args:
+            graph: The graph to validate
+
+        Returns:
+            ValidationResult with any issues found
+        """
+        issues: list[ValidationIssue] = []
+
+        # Check class typing
+        issues.extend(self._check_class_typing(graph))
+
+        # Check property completeness
+        issues.extend(self._check_property_completeness(graph))
+
+        # Check for dangling references
+        issues.extend(self._check_dangling_references(graph))
+
+        return ValidationResult(issues=issues)
+
+    def _check_class_typing(self, graph: Graph) -> list[ValidationIssue]:
+        """Check that classes are properly typed."""
+        issues = []
+
+        # Find subjects of rdfs:subClassOf that aren't typed as classes
+        for s in graph.subjects(RDFS.subClassOf, None):
+            if not isinstance(s, URIRef):
+                continue
+
+            is_class = (
+                (s, RDF.type, OWL.Class) in graph
+                or (s, RDF.type, RDFS.Class) in graph
+            )
+            if not is_class:
+                issues.append(
+                    ValidationIssue(
+                        severity=Severity.WARNING,
+                        code="UNTYPED_CLASS",
+                        message=f"Subject of rdfs:subClassOf not typed as class",
+                        entity=str(s),
+                        suggestion="Add rdf:type owl:Class triple",
+                    )
+                )
+
+        return issues
+
+    def _check_property_completeness(self, graph: Graph) -> list[ValidationIssue]:
+        """Check that properties have domain and range."""
+        issues = []
+
+        for prop in graph.subjects(RDF.type, OWL.ObjectProperty):
+            if not isinstance(prop, URIRef):
+                continue
+
+            has_domain = any(graph.objects(prop, RDFS.domain))
+            has_range = any(graph.objects(prop, RDFS.range))
+
+            if not has_domain:
+                issues.append(
+                    ValidationIssue(
+                        severity=Severity.INFO,
+                        code="MISSING_DOMAIN",
+                        message="Object property has no domain",
+                        entity=str(prop),
+                    )
+                )
+            if not has_range:
+                issues.append(
+                    ValidationIssue(
+                        severity=Severity.INFO,
+                        code="MISSING_RANGE",
+                        message="Object property has no range",
+                        entity=str(prop),
+                    )
+                )
+
+        for prop in graph.subjects(RDF.type, OWL.DatatypeProperty):
+            if not isinstance(prop, URIRef):
+                continue
+
+            has_range = any(graph.objects(prop, RDFS.range))
+            if not has_range:
+                issues.append(
+                    ValidationIssue(
+                        severity=Severity.INFO,
+                        code="MISSING_RANGE",
+                        message="Datatype property has no range (XSD type)",
+                        entity=str(prop),
+                    )
+                )
+
+        return issues
+
+    def _check_dangling_references(self, graph: Graph) -> list[ValidationIssue]:
+        """Check for references to undefined entities."""
+        issues = []
+
+        # Get all defined classes
+        defined_classes = set()
+        for cls in graph.subjects(RDF.type, OWL.Class):
+            defined_classes.add(cls)
+        for cls in graph.subjects(RDF.type, RDFS.Class):
+            defined_classes.add(cls)
+
+        # Check domain and range references
+        for prop in graph.subjects(RDF.type, OWL.ObjectProperty):
+            for domain in graph.objects(prop, RDFS.domain):
+                if isinstance(domain, URIRef) and domain not in defined_classes:
+                    issues.append(
+                        ValidationIssue(
+                            severity=Severity.WARNING,
+                            code="UNDEFINED_DOMAIN",
+                            message=f"Property domain references undefined class",
+                            entity=f"{prop} -> {domain}",
+                        )
+                    )
+
+            for rng in graph.objects(prop, RDFS.range):
+                if isinstance(rng, URIRef) and rng not in defined_classes:
+                    # Could be external class - just info
+                    issues.append(
+                        ValidationIssue(
+                            severity=Severity.INFO,
+                            code="EXTERNAL_RANGE",
+                            message=f"Property range references class not in this graph",
+                            entity=f"{prop} -> {rng}",
+                        )
+                    )
+
+        return issues
+
+
+def validate_puml(model: PumlModel) -> ValidationResult:
+    """Convenience function to validate a PlantUML model.
+
+    Args:
+        model: The parsed model to validate
+
+    Returns:
+        ValidationResult with any issues found
+    """
+    validator = PumlModelValidator()
+    return validator.validate(model)
+
+
+def validate_rdf(graph: Graph) -> ValidationResult:
+    """Convenience function to validate an RDF graph.
+
+    Args:
+        graph: The graph to validate
+
+    Returns:
+        ValidationResult with any issues found
+    """
+    validator = RdfValidator()
+    return validator.validate(graph)

rdf_construct/shacl/__init__.py

@@ -0,0 +1,56 @@
+"""SHACL shape generation from OWL ontologies.
+
+This module provides tools for generating SHACL validation shapes from
+OWL ontology definitions, converting domain/range, cardinality restrictions,
+and other OWL patterns to equivalent SHACL constraints.
+
+Basic usage:
+
+    from rdf_construct.shacl import generate_shapes, ShaclConfig, StrictnessLevel
+
+    # Generate shapes with default settings
+    graph, turtle = generate_shapes(Path("ontology.ttl"))
+
+    # Generate with strict level
+    config = ShaclConfig(level=StrictnessLevel.STRICT, closed=True)
+    graph, turtle = generate_shapes(Path("ontology.ttl"), config)
+
+    # Generate and write to file
+    from rdf_construct.shacl import generate_shapes_to_file
+    generate_shapes_to_file(
+        Path("ontology.ttl"),
+        Path("shapes.ttl"),
+        config,
+    )
+"""
+
+from rdf_construct.shacl.config import (
+    ShaclConfig,
+    Severity,
+    StrictnessLevel,
+    load_shacl_config,
+)
+from rdf_construct.shacl.converters import PropertyConstraint
+from rdf_construct.shacl.generator import (
+    ShapeGenerator,
+    generate_shapes,
+    generate_shapes_to_file,
+)
+from rdf_construct.shacl.namespaces import SH, SHACL_PREFIXES
+
+__all__ = [
+    # Configuration
+    "ShaclConfig",
+    "StrictnessLevel",
+    "Severity",
+    "load_shacl_config",
+    # Generator
+    "ShapeGenerator",
+    "generate_shapes",
+    "generate_shapes_to_file",
+    # Converters
+    "PropertyConstraint",
+    # Namespaces
+    "SH",
+    "SHACL_PREFIXES",
+]

rdf_construct/shacl/config.py

@@ -0,0 +1,166 @@
+"""Configuration handling for SHACL shape generation."""
+
+from dataclasses import dataclass, field
+from enum import Enum
+from pathlib import Path
+from typing import Any
+
+import yaml
+from rdflib import URIRef
+
+
+class StrictnessLevel(Enum):
+    """Strictness levels for SHACL generation.
+
+    Controls how many OWL patterns are converted to SHACL constraints.
+
+    Attributes:
+        MINIMAL: Only basic type constraints (sh:class, sh:datatype).
+        STANDARD: Adds cardinality, functional properties, and common patterns.
+        STRICT: Maximum constraints including sh:closed, all cardinalities.
+    """
+
+    MINIMAL = "minimal"
+    STANDARD = "standard"
+    STRICT = "strict"
+
+
+class Severity(Enum):
+    """SHACL constraint severity levels.
+
+    Maps to sh:Violation, sh:Warning, sh:Info.
+    """
+
+    VIOLATION = "violation"
+    WARNING = "warning"
+    INFO = "info"
+
+
+@dataclass
+class ShaclConfig:
+    """Configuration for SHACL shape generation.
+
+    Controls which OWL patterns are converted and how shapes are structured.
+
+    Attributes:
+        level: Strictness level for conversion.
+        default_severity: Default severity for generated constraints.
+        closed: Generate closed shapes (no extra properties allowed).
+        shape_namespace: Namespace suffix for generated shapes.
+        target_classes: Optional list of classes to generate shapes for.
+        exclude_classes: Classes to skip during generation.
+        include_labels: Include rdfs:label as sh:name.
+        include_descriptions: Include rdfs:comment as sh:description.
+        inherit_constraints: Inherit property constraints from superclasses.
+        generate_property_shapes: Generate top-level PropertyShapes.
+        ignored_properties: Properties to ignore in closed shapes.
+    """
+
+    level: StrictnessLevel = StrictnessLevel.STANDARD
+    default_severity: Severity = Severity.VIOLATION
+    closed: bool = False
+    shape_namespace: str = "shapes#"
+    target_classes: list[str] = field(default_factory=list)
+    exclude_classes: list[str] = field(default_factory=list)
+    include_labels: bool = True
+    include_descriptions: bool = True
+    inherit_constraints: bool = True
+    generate_property_shapes: bool = False
+    ignored_properties: list[str] = field(default_factory=list)
+
+    @classmethod
+    def from_yaml(cls, path: Path) -> "ShaclConfig":
+        """Load configuration from YAML file.
+
+        Args:
+            path: Path to YAML configuration file.
+
+        Returns:
+            Populated ShaclConfig instance.
+
+        Raises:
+            FileNotFoundError: If configuration file doesn't exist.
+            ValueError: If configuration is invalid.
+        """
+        with open(path) as f:
+            data = yaml.safe_load(f) or {}
+
+        return cls.from_dict(data)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "ShaclConfig":
+        """Create configuration from dictionary.
+
+        Args:
+            data: Configuration dictionary.
+
+        Returns:
+            Populated ShaclConfig instance.
+        """
+        # Handle enum conversions
+        level_str = data.get("level", "standard").lower()
+        try:
+            level = StrictnessLevel(level_str)
+        except ValueError:
+            valid = ", ".join(s.value for s in StrictnessLevel)
+            raise ValueError(f"Invalid strictness level '{level_str}'. Valid: {valid}")
+
+        severity_str = data.get("default_severity", "violation").lower()
+        try:
+            severity = Severity(severity_str)
+        except ValueError:
+            valid = ", ".join(s.value for s in Severity)
+            raise ValueError(f"Invalid severity '{severity_str}'. Valid: {valid}")
+
+        return cls(
+            level=level,
+            default_severity=severity,
+            closed=data.get("closed", False),
+            shape_namespace=data.get("shape_namespace", "shapes#"),
+            target_classes=data.get("target_classes", []),
+            exclude_classes=data.get("exclude_classes", []),
+            include_labels=data.get("include_labels", True),
+            include_descriptions=data.get("include_descriptions", True),
+            inherit_constraints=data.get("inherit_constraints", True),
+            generate_property_shapes=data.get("generate_property_shapes", False),
+            ignored_properties=data.get("ignored_properties", []),
+        )
+
+    def should_generate_for(self, class_uri: URIRef, graph: "Graph") -> bool:
+        """Check if a shape should be generated for this class.
+
+        Args:
+            class_uri: The class URI to check.
+            graph: The source graph (for CURIE expansion).
+
+        Returns:
+            True if shape should be generated.
+        """
+        class_str = str(class_uri)
+
+        # If explicit targets specified, only generate for those
+        if self.target_classes:
+            return any(class_str.endswith(t) or t in class_str for t in self.target_classes)
+
+        # Check exclusions
+        if self.exclude_classes:
+            return not any(
+                class_str.endswith(e) or e in class_str for e in self.exclude_classes
+            )
+
+        return True
+
+
+def load_shacl_config(path: Path | None) -> ShaclConfig:
+    """Load SHACL configuration from file or return defaults.
+
+    Args:
+        path: Optional path to configuration file.
+
+    Returns:
+        ShaclConfig instance (defaults if no path provided).
+    """
+    if path is None:
+        return ShaclConfig()
+
+    return ShaclConfig.from_yaml(path)