Merge pull request #20 from AtomGraph/feat-spec-portal-ops

Spec and unit tests for portal/ontology operations

Author: namedgraph

formal-semantics.md

@@ -258,6 +258,24 @@ Abstract: URI × Maybe URI → Any
 Python:   def execute(self, url: URIRef, block: URIRef = None) -> Any
 ```
 
+**ldh-GenerateOntologyViews** - Generate LDH views (`ldh:view`) and SPIN `sp:Select` queries for each non-`owl:FunctionalProperty` `owl:DatatypeProperty`/`owl:ObjectProperty` in an ontology graph
+```
+Abstract: Graph × URI × URI → Graph
+Python:   def execute(self, ontology: rdflib.Graph, base_uri: URIRef, service_uri: URIRef) -> rdflib.Graph
+```
+
+**ldh-GenerateClassContainers** - Create an LDH container per `owl:Class` in an ontology graph (each with a SPARQL service and instance-list view)
+```
+Abstract: Graph × URI × URI → Result
+Python:   def execute(self, ontology: rdflib.Graph, parent_container: URIRef, endpoint: URIRef) -> Result
+```
+
+**ldh-GeneratePortal** - End-to-end portal generation; composes `ExtractOntology`, `ldh-GenerateOntologyViews`, `POST`, and `ldh-GenerateClassContainers`
+```
+Abstract: URI × URI × URI → Result
+Python:   def execute(self, endpoint: URIRef, ontology_namespace: URIRef, parent_container: URIRef) -> Result
+```
+
 ### Schema Operations
 
 **ExtractClasses** - Extract RDF classes from graph
@@ -278,6 +296,12 @@ Abstract: URI → Graph
 Python:   def execute(self, endpoint: URIRef) -> rdflib.Graph
 ```
 
+**ExtractOntology** - Extract a full ontology (classes + datatype + object properties) from a SPARQL endpoint as a single graph
+```
+Abstract: URI → Graph
+Python:   def execute(self, endpoint: URIRef) -> rdflib.Graph
+```
+
 ### Utility Operations
 
 **Merge** - Merge multiple RDF graphs into one

src/web_algebra/operations/linkeddatahub/content/generate_class_containers.py

@@ -60,6 +60,18 @@ def execute(self, ontology: Graph, parent_container: URIRef, endpoint: URIRef) -
         Returns:
             Concatenated Result containing all operation results (CreateContainer + AddGenericService + POST bindings)
         """
+        if not isinstance(ontology, Graph):
+            raise TypeError(
+                f"GenerateClassContainers operation expects 'ontology' to be Graph, got {type(ontology)}"
+            )
+        if not isinstance(parent_container, URIRef):
+            raise TypeError(
+                f"GenerateClassContainers operation expects 'parent_container' to be URIRef, got {type(parent_container)}"
+            )
+        if not isinstance(endpoint, URIRef):
+            raise TypeError(
+                f"GenerateClassContainers operation expects 'endpoint' to be URIRef, got {type(endpoint)}"
+            )
         # Define namespaces
         LDH = Namespace("https://w3id.org/atomgraph/linkeddatahub#")
         SP = Namespace("http://spinrdf.org/sp#")

src/web_algebra/operations/linkeddatahub/content/generate_ontology_views.py

@@ -56,6 +56,19 @@ def execute(self, ontology: Graph, base_uri: URIRef, service_uri: URIRef) -> Gra
         Returns:
             RDF graph containing ldh:View, sp:Select, and ldh:view triples
         """
+        if not isinstance(ontology, Graph):
+            raise TypeError(
+                f"GenerateOntologyViews operation expects 'ontology' to be Graph, got {type(ontology)}"
+            )
+        if not isinstance(base_uri, URIRef):
+            raise TypeError(
+                f"GenerateOntologyViews operation expects 'base_uri' to be URIRef, got {type(base_uri)}"
+            )
+        if not isinstance(service_uri, URIRef):
+            raise TypeError(
+                f"GenerateOntologyViews operation expects 'service_uri' to be URIRef, got {type(service_uri)}"
+            )
+
         # Define namespaces
         LDH = Namespace("https://w3id.org/atomgraph/linkeddatahub#")
         SP = Namespace("http://spinrdf.org/sp#")

src/web_algebra/operations/linkeddatahub/content/generate_portal.py

@@ -51,6 +51,19 @@ def execute(self, endpoint: URIRef, ontology_namespace: URIRef, parent_container
         Returns:
             Concatenated Result containing all operation results
         """
+        if not isinstance(endpoint, URIRef):
+            raise TypeError(
+                f"GeneratePortal operation expects 'endpoint' to be URIRef, got {type(endpoint)}"
+            )
+        if not isinstance(ontology_namespace, URIRef):
+            raise TypeError(
+                f"GeneratePortal operation expects 'ontology_namespace' to be URIRef, got {type(ontology_namespace)}"
+            )
+        if not isinstance(parent_container, URIRef):
+            raise TypeError(
+                f"GeneratePortal operation expects 'parent_container' to be URIRef, got {type(parent_container)}"
+            )
+
         import logging
 
         # Step 0: Create service resource for the SPARQL endpoint

src/web_algebra/operations/schema/extract_ontology.py

@@ -27,6 +27,10 @@ def inputSchema(cls) -> dict:
 
     def execute(self, endpoint: URIRef) -> Graph:
         """Extract complete ontology by composing individual extraction operations"""
+        if not isinstance(endpoint, URIRef):
+            raise TypeError(
+                f"ExtractOntology operation expects 'endpoint' to be URIRef, got {type(endpoint)}"
+            )
 
         # Extract classes
         classes_graph = ExtractClasses(settings=self.settings, context=self.context).execute(endpoint)

tests/unit/test_extract_ontology.py

@@ -0,0 +1,29 @@
+"""Spec: formal-semantics.md "ExtractOntology - Extract a full ontology (classes
++ datatype + object properties) from a SPARQL endpoint as a single graph"
+Abstract: URI → Graph
+Python:   def execute(self, endpoint: URIRef) -> rdflib.Graph
+"""
+
+from __future__ import annotations
+
+import pytest
+from rdflib import Literal
+
+from web_algebra.operation import Operation
+
+
+class TestExtractOntologyPure:
+    def test_wrong_input_type_raises(self, settings):
+        op = Operation.get("ExtractOntology")(settings=settings)
+        with pytest.raises(TypeError):
+            op.execute(Literal("not-a-uri"))
+
+    @pytest.mark.skip(reason="UNCLEAR(spec): is the URI a SPARQL endpoint, document URL, or ontology IRI? — narrative omits this")
+    def test_happy_path(self, settings):
+        pass
+
+
+class TestExtractOntologyJson:
+    @pytest.mark.skip(reason="UNCLEAR(spec): JSON arg key for ExtractOntology not given by spec or existing fixtures")
+    def test_json_dispatch(self, settings):
+        pass

tests/unit/test_ldh_generate_class_containers.py

@@ -0,0 +1,47 @@
+"""Spec: formal-semantics.md "ldh-GenerateClassContainers - Create an LDH
+container per `owl:Class` in an ontology graph (each with a SPARQL service and
+instance-list view)"
+Abstract: Graph × URI × URI → Result
+Python:   def execute(self, ontology: rdflib.Graph, parent_container: URIRef, endpoint: URIRef) -> Result
+"""
+
+from __future__ import annotations
+
+import pytest
+from rdflib import Graph, Literal, URIRef
+
+from web_algebra.operation import Operation
+
+
+PARENT = URIRef("http://example.org/portal/")
+ENDPOINT = URIRef("http://example.org/sparql")
+
+
+class TestLDHGenerateClassContainersPure:
+    def test_wrong_ontology_type_raises(self, settings):
+        op = Operation.get("ldh-GenerateClassContainers")(settings=settings)
+        with pytest.raises(TypeError):
+            op.execute(Literal("not-a-graph"), PARENT, ENDPOINT)
+
+    def test_wrong_parent_container_type_raises(self, settings):
+        op = Operation.get("ldh-GenerateClassContainers")(settings=settings)
+        with pytest.raises(TypeError):
+            op.execute(Graph(), Literal("not-a-uri"), ENDPOINT)
+
+    def test_wrong_endpoint_type_raises(self, settings):
+        op = Operation.get("ldh-GenerateClassContainers")(settings=settings)
+        with pytest.raises(TypeError):
+            op.execute(Graph(), PARENT, Literal("not-a-uri"))
+
+
+@pytest.mark.ldh
+class TestLDHGenerateClassContainersLive:
+    @pytest.mark.skip(reason="UNCLEAR(spec): return type `Result` shape — what's a meaningful assertion for a side-effecting orchestration?")
+    def test_basic(self, settings_with_auth):
+        pass
+
+
+class TestLDHGenerateClassContainersJson:
+    @pytest.mark.skip(reason="UNCLEAR(spec): JSON arg keys for ldh-GenerateClassContainers not given by spec or existing fixtures")
+    def test_json_dispatch(self, settings):
+        pass

tests/unit/test_ldh_generate_ontology_views.py

@@ -0,0 +1,80 @@
+"""Spec: formal-semantics.md "ldh-GenerateOntologyViews - Generate LDH views
+(`ldh:view`) and SPIN `sp:Select` queries for each non-`owl:FunctionalProperty`
+`owl:DatatypeProperty`/`owl:ObjectProperty` in an ontology graph"
+Abstract: Graph × URI × URI → Graph
+Python:   def execute(self, ontology: rdflib.Graph, base_uri: URIRef, service_uri: URIRef) -> rdflib.Graph
+"""
+
+from __future__ import annotations
+
+import pytest
+from rdflib import Graph, Literal, Namespace, URIRef
+from rdflib.namespace import OWL, RDF
+
+from web_algebra.operation import Operation
+
+
+LDH = Namespace("https://w3id.org/atomgraph/linkeddatahub#")
+EX = Namespace("http://example.org/ns#")
+BASE = URIRef("http://example.org/portal/")
+SERVICE = URIRef("http://example.org/portal/#Service")
+
+
+class TestLDHGenerateOntologyViewsPure:
+    def test_wrong_ontology_type_raises(self, settings):
+        op = Operation.get("ldh-GenerateOntologyViews")(settings=settings)
+        with pytest.raises(TypeError):
+            op.execute(Literal("not-a-graph"), BASE, SERVICE)
+
+    def test_wrong_base_uri_type_raises(self, settings):
+        op = Operation.get("ldh-GenerateOntologyViews")(settings=settings)
+        with pytest.raises(TypeError):
+            op.execute(Graph(), Literal("not-a-uri"), SERVICE)
+
+    def test_wrong_service_uri_type_raises(self, settings):
+        op = Operation.get("ldh-GenerateOntologyViews")(settings=settings)
+        with pytest.raises(TypeError):
+            op.execute(Graph(), BASE, Literal("not-a-uri"))
+
+    def test_emits_ldh_view_for_non_functional_property(self, settings):
+        """Spec: emits a view per non-`owl:FunctionalProperty` object/datatype property."""
+        ontology = Graph()
+        ontology.add((EX.knows, RDF.type, OWL.ObjectProperty))
+
+        op = Operation.get("ldh-GenerateOntologyViews")(settings=settings)
+        out = op.execute(ontology, BASE, SERVICE)
+
+        assert isinstance(out, Graph)
+        views = list(out.triples((EX.knows, LDH.view, None)))
+        assert len(views) == 1, f"expected one ldh:view triple for ex:knows, got {len(views)}"
+
+    def test_skips_functional_property(self, settings):
+        """Spec: properties declared `owl:FunctionalProperty` are excluded."""
+        ontology = Graph()
+        ontology.add((EX.ssn, RDF.type, OWL.DatatypeProperty))
+        ontology.add((EX.ssn, RDF.type, OWL.FunctionalProperty))
+
+        op = Operation.get("ldh-GenerateOntologyViews")(settings=settings)
+        out = op.execute(ontology, BASE, SERVICE)
+
+        views = list(out.triples((EX.ssn, LDH.view, None)))
+        assert len(views) == 0, "functional property must not get a view"
+
+    def test_no_ldh_template_in_output(self, settings):
+        """Spec phrases the output predicate as `ldh:view` — `ldh:template` (the
+        previous LDH vocabulary, since removed) must not appear."""
+        ontology = Graph()
+        ontology.add((EX.knows, RDF.type, OWL.ObjectProperty))
+        ontology.add((EX.name, RDF.type, OWL.DatatypeProperty))
+
+        op = Operation.get("ldh-GenerateOntologyViews")(settings=settings)
+        out = op.execute(ontology, BASE, SERVICE)
+
+        legacy = list(out.triples((None, LDH.template, None)))
+        assert legacy == [], "output must contain no `ldh:template` triples"
+
+
+class TestLDHGenerateOntologyViewsJson:
+    @pytest.mark.skip(reason="UNCLEAR(spec): JSON arg keys for ldh-GenerateOntologyViews not given by spec or existing fixtures")
+    def test_json_dispatch(self, settings):
+        pass

tests/unit/test_ldh_generate_portal.py

@@ -0,0 +1,48 @@
+"""Spec: formal-semantics.md "ldh-GeneratePortal - End-to-end portal generation;
+composes `ExtractOntology`, `ldh-GenerateOntologyViews`, `POST`, and
+`ldh-GenerateClassContainers`"
+Abstract: URI × URI × URI → Result
+Python:   def execute(self, endpoint: URIRef, ontology_namespace: URIRef, parent_container: URIRef) -> Result
+"""
+
+from __future__ import annotations
+
+import pytest
+from rdflib import Literal, URIRef
+
+from web_algebra.operation import Operation
+
+
+ENDPOINT = URIRef("http://example.org/sparql")
+ONTOLOGY_NS = URIRef("http://example.org/ontology/")
+PARENT = URIRef("http://example.org/portal/")
+
+
+class TestLDHGeneratePortalPure:
+    def test_wrong_endpoint_type_raises(self, settings):
+        op = Operation.get("ldh-GeneratePortal")(settings=settings)
+        with pytest.raises(TypeError):
+            op.execute(Literal("not-a-uri"), ONTOLOGY_NS, PARENT)
+
+    def test_wrong_ontology_namespace_type_raises(self, settings):
+        op = Operation.get("ldh-GeneratePortal")(settings=settings)
+        with pytest.raises(TypeError):
+            op.execute(ENDPOINT, Literal("not-a-uri"), PARENT)
+
+    def test_wrong_parent_container_type_raises(self, settings):
+        op = Operation.get("ldh-GeneratePortal")(settings=settings)
+        with pytest.raises(TypeError):
+            op.execute(ENDPOINT, ONTOLOGY_NS, Literal("not-a-uri"))
+
+
+@pytest.mark.ldh
+class TestLDHGeneratePortalLive:
+    @pytest.mark.skip(reason="UNCLEAR(spec): return type `Result` shape — what's a meaningful assertion for end-to-end portal generation?")
+    def test_basic(self, settings_with_auth):
+        pass
+
+
+class TestLDHGeneratePortalJson:
+    @pytest.mark.skip(reason="UNCLEAR(spec): JSON arg keys for ldh-GeneratePortal not given by spec or existing fixtures")
+    def test_json_dispatch(self, settings):
+        pass