validibot-shared 0.8.0__tar.gz → 0.9.0__tar.gz

{validibot_shared-0.8.0 → validibot_shared-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: validibot-shared
-Version: 0.8.0
+Version: 0.9.0
 Summary: Shared library for data interchange between Validibot and validator containers
 Project-URL: Homepage, https://validibot.com
 Project-URL: Documentation, https://docs.validibot.com
@@ -11,7 +11,7 @@ Maintainer-email: Daniel McQuillen <daniel@validibot.com>
 License: MIT
 License-File: LICENSE
 License-File: NOTICE
-Keywords: data-interchange,energyplus,fmu,simulation,validation,validibot
+Keywords: data-interchange,energyplus,fmu,rdf,shacl,simulation,validation,validibot
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License

{validibot_shared-0.8.0 → validibot_shared-0.9.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "validibot-shared"
-version = "0.8.0"
+version = "0.9.0"
 description = "Shared library for data interchange between Validibot and validator containers"
 readme = "README.md"
 license = { text = "MIT" }
@@ -16,6 +16,8 @@ keywords = [
     "validation",
     "energyplus",
     "fmu",
+    "shacl",
+    "rdf",
     "simulation",
     "data-interchange",
 ]

validibot_shared-0.9.0/tests/test_shacl_envelopes.py

@@ -0,0 +1,267 @@
+"""Tests for the SHACL Advanced validator envelopes.
+
+This suite covers the contract that lets Django hand SHACL validation off to an
+isolated container backend. The container parses untrusted RDF and runs
+author-supplied SPARQL, so the envelope boundary is security-critical: anything
+the container needs must travel *in* the envelope (no database, no settings, no
+secrets reachable from the container), and anything it produces must round-trip
+back to Django through ``SHACLOutputs``.
+
+We therefore assert three things:
+
+1. The typed envelopes accept well-formed payloads and round-trip through JSON
+   (Django serializes the input; the container serializes the output).
+2. ``extra="forbid"`` is honoured so a drifting producer/consumer fails loudly
+   rather than silently dropping fields across the trust boundary.
+3. The ``SHACLOutputs`` signal fields stay aligned with what Django's
+   ``extract_output_signals`` expects (the ``o.*`` catalog keys).
+"""
+
+import pytest
+from pydantic import ValidationError
+
+from validibot_shared.shacl.envelopes import (
+    SHACL_RESULT_REPORT_ONLY,
+    SHACLInputEnvelope,
+    SHACLInputs,
+    SHACLOutputEnvelope,
+    SHACLOutputs,
+    SHACLSparqlAssertionSpec,
+    build_shacl_input_envelope,
+    mime_type_for_rdf_format,
+)
+from validibot_shared.validations.envelopes import (
+    ExecutionContext,
+    SupportedMimeType,
+    ValidationStatus,
+    ValidatorType,
+)
+
+# The o.* signal keys Django's SHACL catalog declares. If SHACLOutputs ever
+# drops one of these, the Django extractor would silently lose a CEL signal —
+# this list is the canary.
+EXPECTED_SIGNAL_KEYS = {
+    "parse_ok",
+    "parse_serialization",
+    "triple_count",
+    "namespaces_present",
+    "has_s223_namespace",
+    "has_g36_namespace",
+    "has_brick_namespace",
+    "shacl_violation_count",
+    "shacl_warning_count",
+    "shacl_info_count",
+    "shacl_total_count",
+}
+
+
+def _base_kwargs():
+    """Minimal valid envelope metadata shared by the input-envelope tests."""
+    return {
+        "run_id": "run-123",
+        "validator": {"id": "val-1", "type": ValidatorType.SHACL, "version": "1"},
+        "org": {"id": "org-1", "name": "ValidiBot"},
+        "workflow": {"id": "wf-1", "step_id": "step-1", "step_name": "SHACL"},
+        "context": ExecutionContext(
+            callback_url="https://example.com/cb",
+            execution_bundle_uri="gs://bucket/run-123/",
+        ),
+    }
+
+
+# ── Input envelope ──────────────────────────────────────────────────────────
+# The input envelope is what Django writes to storage before triggering the
+# container. It must carry the merged shapes, resolved settings, and the
+# author's SPARQL-ASK assertions, because the container has no DB to read them.
+
+
+def test_shacl_input_envelope_requires_typed_inputs():
+    """The envelope must coerce a raw dict into a typed ``SHACLInputs``.
+
+    Django builds the inputs as a dict in some code paths; the typed override on
+    ``SHACLInputEnvelope.inputs`` is what guarantees the container receives a
+    validated structure rather than arbitrary JSON.
+    """
+    envelope = SHACLInputEnvelope(
+        **_base_kwargs(),
+        input_files=[],
+        inputs={
+            "shapes_text": "@prefix sh: <http://www.w3.org/ns/shacl#> .",
+            "rdf_format": "turtle",
+            "inference_mode": "rdfs",
+            "sparql_ask_assertions": [
+                {"target_graph": "data", "query": "ASK { ?s ?p ?o }"},
+            ],
+        },
+    )
+
+    assert envelope.inputs.shapes_text.startswith("@prefix sh:")
+    assert envelope.inputs.sparql_ask_assertions[0].target_graph == "data"
+    # advanced features default off — the deployment gate must be opt-in.
+    assert envelope.inputs.advanced_shacl is False
+    assert envelope.inputs.enable_advanced_features is False
+
+
+def test_shacl_inputs_rejects_nonpositive_limits():
+    """Resource limits must be positive so a corrupt envelope can't disable caps.
+
+    A zero/negative triple cap would mean "no limit" if it slipped through — the
+    container relies on these bounds as a DoS backstop, so the schema refuses
+    them at the boundary.
+    """
+    with pytest.raises(ValidationError):
+        SHACLInputs(shapes_text="x", max_data_triples=0)
+    with pytest.raises(ValidationError):
+        SHACLInputs(shapes_text="x", pyshacl_timeout_seconds=-1)
+
+
+def test_shacl_input_envelope_forbids_unknown_fields():
+    """Unknown top-level keys are rejected (``extra='forbid'``).
+
+    Silent field-dropping across the Django/container trust boundary would let a
+    contract mismatch pass unnoticed; we want a hard failure instead.
+    """
+    with pytest.raises(ValidationError):
+        SHACLInputEnvelope(
+            **_base_kwargs(),
+            input_files=[],
+            inputs={"shapes_text": "x"},
+            unexpected="nope",
+        )
+
+
+def test_build_shacl_input_envelope_constructs_expected_payload():
+    """The helper wires the submission file, role, and MIME type correctly.
+
+    The container reads ``input_files[0].uri`` to fetch the RDF graph, and the
+    MIME type is derived from the resolved rdflib format — this proves the helper
+    produces a fetchable, correctly-typed input file.
+    """
+    inputs = SHACLInputs(
+        shapes_text="@prefix sh: <http://www.w3.org/ns/shacl#> .",
+        rdf_format="json-ld",
+    )
+    envelope = build_shacl_input_envelope(
+        run_id="run-1",
+        validator=type(
+            "Validator",
+            (),
+            {"id": 1, "validation_type": ValidatorType.SHACL, "version": "2"},
+        )(),
+        org_id="org-1",
+        org_name="ValidiBot",
+        workflow_id="wf-1",
+        step_id="step-1",
+        step_name="Validate graph",
+        submission_uri="gs://bucket/submission.jsonld",
+        inputs=inputs,
+        callback_url="https://example.com/callback",
+        execution_bundle_uri="gs://bucket/run-1/",
+        skip_callback=True,
+    )
+
+    assert envelope.input_files[0].uri == "gs://bucket/submission.jsonld"
+    assert envelope.input_files[0].role == "primary-model"
+    assert envelope.input_files[0].mime_type == SupportedMimeType.RDF_JSON_LD
+    assert envelope.validator.version == "2"
+    assert envelope.context.skip_callback is True
+
+
+def test_mime_type_for_rdf_format_defaults_to_turtle():
+    """An unknown format falls back to Turtle, the most common SHACL encoding.
+
+    Defaulting (rather than raising) keeps a slightly-off format hint from
+    blocking a run; the container still parses using the explicit ``rdf_format``.
+    """
+    assert mime_type_for_rdf_format("turtle") == SupportedMimeType.RDF_TURTLE
+    assert mime_type_for_rdf_format("xml") == SupportedMimeType.RDF_XML
+    assert mime_type_for_rdf_format("totally-unknown") == SupportedMimeType.RDF_TURTLE
+
+
+# ── SPARQL-ASK spec ─────────────────────────────────────────────────────────
+# SPARQL-ASK assertions touch the graph, so they execute in the container, not
+# in Django. The spec is the serialized form of a RulesetAssertion row.
+
+
+def test_sparql_assertion_spec_defaults():
+    """A spec needs only a query; everything else has a safe default.
+
+    Defaulting ``severity`` to ERROR and ``target_graph`` to the data graph
+    matches the engine's historical behaviour so existing assertions keep their
+    meaning after the move to the container.
+    """
+    spec = SHACLSparqlAssertionSpec(query="ASK { ?s a ?type }")
+    assert spec.severity == "ERROR"
+    assert spec.target_graph == "data"
+    assert spec.assertion_id is None
+
+
+# ── Output envelope ─────────────────────────────────────────────────────────
+# The output envelope is what the container writes back. Its signal fields feed
+# Django's CEL/Basic assertion evaluation; its assertion tallies are folded into
+# the final AssertionStats.
+
+
+def test_shacl_outputs_signal_keys_cover_catalog():
+    """Every catalog signal key must exist as a field on ``SHACLOutputs``.
+
+    Django's ``extract_output_signals`` reads these keys off the envelope; a
+    missing field here would surface as a null CEL signal at runtime with no
+    error. This test pins the alignment at the contract layer.
+    """
+    field_names = set(SHACLOutputs.model_fields)
+    missing = EXPECTED_SIGNAL_KEYS - field_names
+    assert not missing, f"SHACLOutputs missing signal fields: {missing}"
+
+
+def test_shacl_output_envelope_round_trips():
+    """A full output envelope round-trips through JSON unchanged.
+
+    Django deserializes ``output.json`` written by the container; this proves the
+    typed subclass reconstructs the ``SHACLOutputs`` (including the serialized
+    report and assertion counts) faithfully.
+    """
+    envelope = SHACLOutputEnvelope(
+        run_id="run-123",
+        validator={"id": "val-1", "type": ValidatorType.SHACL, "version": "1"},
+        status=ValidationStatus.FAILED_VALIDATION,
+        timing={},
+        messages=[],
+        outputs=SHACLOutputs(
+            conforms=False,
+            parse_ok=True,
+            parse_serialization="turtle",
+            triple_count=42,
+            has_s223_namespace=True,
+            shacl_violation_count=2,
+            shacl_total_count=2,
+            results_graph_turtle="@prefix sh: <http://www.w3.org/ns/shacl#> .",
+            shacl_result_handling=SHACL_RESULT_REPORT_ONLY,
+            assertion_total=3,
+            assertion_failures=1,
+            execution_seconds=0.5,
+        ),
+    )
+
+    restored = SHACLOutputEnvelope.model_validate_json(envelope.model_dump_json())
+    assert restored.outputs.conforms is False
+    assert restored.outputs.triple_count == 42
+    assert restored.outputs.assertion_failures == 1
+    assert restored.status == ValidationStatus.FAILED_VALIDATION
+
+
+def test_shacl_output_envelope_allows_none_outputs():
+    """``outputs`` may be None for a runtime failure before SHACL produced a report.
+
+    The container sets a FAILED_RUNTIME status with ``outputs=None`` when, e.g.,
+    the submission fails to parse — Django must still be able to deserialize that
+    envelope to surface the failure.
+    """
+    envelope = SHACLOutputEnvelope(
+        run_id="run-123",
+        validator={"id": "val-1", "type": ValidatorType.SHACL, "version": "1"},
+        status=ValidationStatus.FAILED_RUNTIME,
+        timing={},
+        outputs=None,
+    )
+    assert envelope.outputs is None

{validibot_shared-0.8.0 → validibot_shared-0.9.0}/validibot_shared/__init__.py

@@ -16,6 +16,13 @@ from validibot_shared.evidence import (
     WorkflowContractSnapshot,
 )
 from validibot_shared.fmu.models import FMUProbeResult, FMUVariableMeta
+from validibot_shared.shacl.envelopes import (
+    SHACLInputEnvelope,
+    SHACLInputs,
+    SHACLOutputEnvelope,
+    SHACLOutputs,
+    SHACLSparqlAssertionSpec,
+)
 
 __all__ = [
     "EVIDENCE_SCHEMA_VERSION",
@@ -27,6 +34,11 @@ __all__ = [
     "FMUVariableMeta",
     "ManifestPayloadDigests",
     "ManifestRetentionInfo",
+    "SHACLInputEnvelope",
+    "SHACLInputs",
+    "SHACLOutputEnvelope",
+    "SHACLOutputs",
+    "SHACLSparqlAssertionSpec",
     "StepValidatorRecord",
     "WorkflowContractSnapshot",
 ]

validibot_shared-0.9.0/validibot_shared/shacl/__init__.py

@@ -0,0 +1,35 @@
+"""SHACL Advanced validator envelopes and models."""
+
+from validibot_shared.shacl.envelopes import (
+    SHACL_RESULT_FAIL_AFTER_ASSERTIONS,
+    SHACL_RESULT_FAIL_IMMEDIATELY,
+    SHACL_RESULT_REPORT_ONLY,
+    SPARQL_ASK_TARGET_DATA,
+    SPARQL_ASK_TARGET_RESULTS,
+    SPARQL_ASK_TARGET_UNION,
+    SHACLFinding,
+    SHACLInputEnvelope,
+    SHACLInputs,
+    SHACLOutputEnvelope,
+    SHACLOutputs,
+    SHACLSparqlAssertionSpec,
+    build_shacl_input_envelope,
+    mime_type_for_rdf_format,
+)
+
+__all__ = [
+    "SHACL_RESULT_FAIL_AFTER_ASSERTIONS",
+    "SHACL_RESULT_FAIL_IMMEDIATELY",
+    "SHACL_RESULT_REPORT_ONLY",
+    "SPARQL_ASK_TARGET_DATA",
+    "SPARQL_ASK_TARGET_RESULTS",
+    "SPARQL_ASK_TARGET_UNION",
+    "SHACLFinding",
+    "SHACLInputEnvelope",
+    "SHACLInputs",
+    "SHACLOutputEnvelope",
+    "SHACLOutputs",
+    "SHACLSparqlAssertionSpec",
+    "build_shacl_input_envelope",
+    "mime_type_for_rdf_format",
+]

validibot_shared-0.9.0/validibot_shared/shacl/envelopes.py

@@ -0,0 +1,339 @@
+"""
+Pydantic envelopes for the SHACL Advanced validator backend.
+
+The SHACL validator is an Advanced validator — it runs in an isolated
+container/Cloud Run Job rather than inside the Django worker. That isolation is
+the whole point: SHACL parses untrusted RDF and executes author-supplied SPARQL
+(SHACL-AF constraints and SPARQL-ASK assertions), and we never want that running
+next to the worker's database credentials, service-account identity, or network.
+
+These schemas define the contract between Django and the SHACL container:
+
+- **Input envelope**: the RDF submission (as an ``InputFileItem`` URI) plus the
+  merged shape/ontology text, the resolved engine settings, the resource limits,
+  and the author-defined SPARQL-ASK assertions. Django resolves all of this from
+  the database (rulesets, ``RulesetAssertion`` rows, settings) before dispatch —
+  the container receives only this serialized boundary.
+- **Output envelope**: the SHACL findings (as ``ValidationMessage`` rows), the
+  ``o.*`` signal dict (for CEL/Basic output assertions evaluated back in Django),
+  the serialized ``sh:ValidationReport`` for evidence download, and the
+  container-side SPARQL-ASK assertion counts (folded into the final assertion
+  totals by ``AdvancedValidator.post_execute_validate``).
+
+See ADR-2026-05-18 for the SHACL engine design and the cross-repo plan for the
+isolation rationale.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from validibot_shared.validations.envelopes import (
+    ExecutionContext,
+    InputFileItem,
+    SupportedMimeType,
+    ValidationInputEnvelope,
+    ValidationOutputEnvelope,
+    ValidatorInfo,
+    ValidatorType,
+)
+
+# Result-handling modes. Mirrors
+# ``validibot.validations.validators.shacl.constants`` on the Django side; the
+# container applies the resolved mode to decide which findings block.
+SHACL_RESULT_FAIL_IMMEDIATELY = "fail_immediately"
+SHACL_RESULT_FAIL_AFTER_ASSERTIONS = "fail_after_assertions"
+SHACL_RESULT_REPORT_ONLY = "report_only"
+
+# SPARQL-ASK target graphs.
+SPARQL_ASK_TARGET_DATA = "data"
+SPARQL_ASK_TARGET_RESULTS = "results"
+SPARQL_ASK_TARGET_UNION = "union"
+
+
+class SHACLSparqlAssertionSpec(BaseModel):
+    """One author-defined SPARQL-ASK assertion to run inside the container.
+
+    Django rehydrates each ``RulesetAssertion`` row (``assertion_type=SHACL``)
+    into one of these specs and ships it in the input envelope. The container
+    re-scrubs ``query`` through the AST scrubber before executing it — the form
+    already scrubbed at save time, but the runtime re-check is belt-and-braces
+    against fixtures/imports that bypass the form.
+    """
+
+    target_graph: str = Field(
+        default=SPARQL_ASK_TARGET_DATA,
+        description="Which graph to run the ASK against: data | results | union.",
+    )
+    query: str = Field(description="Raw SPARQL ASK query text.")
+    severity: str = Field(
+        default="ERROR",
+        description=(
+            "Validibot severity emitted on a false answer (ERROR/WARNING/INFO)."
+        ),
+    )
+    description: str = Field(default="", description="Human-readable label.")
+    error_message_template: str = Field(
+        default="",
+        description="Message shown when the ASK returns false.",
+    )
+    success_message: str = Field(
+        default="",
+        description="Optional message recorded when the ASK returns true.",
+    )
+    assertion_id: int | None = Field(
+        default=None,
+        description="RulesetAssertion.pk, for finding attribution back in Django.",
+    )
+
+    model_config = {"extra": "forbid"}
+
+
+class SHACLInputs(BaseModel):
+    """SHACL engine configuration resolved by Django and run in the container.
+
+    Everything the container needs to validate without any database access. The
+    shape/ontology text is already merged (library default + step extras), the
+    RDF format is already resolved from the submission filename, and the resource
+    limits are already clamped to their hard caps Django-side — the container
+    treats these as authoritative but still hard-caps defensively.
+    """
+
+    shapes_text: str = Field(description="Merged SHACL shapes graph (Turtle).")
+    ontology_text: str = Field(
+        default="",
+        description="Optional merged ontology graph (Turtle) for inference.",
+    )
+    rdf_format: str = Field(
+        default="turtle",
+        description=(
+            "Resolved rdflib format slug for the submission "
+            "(turtle | json-ld | xml | nt | nquads)."
+        ),
+    )
+    inference_mode: str = Field(
+        default="rdfs",
+        description="pyshacl inference mode: none | rdfs | owlrl | both.",
+    )
+    advanced_shacl: bool = Field(
+        default=False,
+        description="Whether the author requested SHACL-AF / embedded SPARQL.",
+    )
+    enable_advanced_features: bool = Field(
+        default=False,
+        description=(
+            "Deployment gate forwarded from SHACL_ENABLE_ADVANCED_FEATURES. "
+            "Even when advanced_shacl is requested, embedded SPARQL execution is "
+            "only accepted when this is also true."
+        ),
+    )
+    submission_format: str = Field(
+        default="auto",
+        description=(
+            "Original author-selected submission format (auto/turtle/...). "
+            "Retained for diagnostics; the container parses using rdf_format."
+        ),
+    )
+    shacl_result_handling: str = Field(
+        default=SHACL_RESULT_FAIL_AFTER_ASSERTIONS,
+        description="fail_immediately | fail_after_assertions | report_only.",
+    )
+    bundled_standards: list[str] = Field(
+        default_factory=list,
+        description="Opted-in bundled standard identifiers (e.g. brick-1.4).",
+    )
+    sparql_ask_assertions: list[SHACLSparqlAssertionSpec] = Field(
+        default_factory=list,
+        description="Author-defined SPARQL-ASK assertions to evaluate post-SHACL.",
+    )
+
+    # ── Resource limits (already clamped Django-side; re-clamped in container) ──
+    max_data_triples: int = Field(default=100_000, gt=0)
+    max_shape_triples: int = Field(default=50_000, gt=0)
+    max_ontology_triples: int = Field(default=100_000, gt=0)
+    max_validation_depth: int = Field(default=25, gt=0)
+    pyshacl_timeout_seconds: int = Field(default=30, gt=0)
+    sparql_query_timeout_seconds: int = Field(default=10, gt=0)
+
+    model_config = {"extra": "forbid"}
+
+
+class SHACLFinding(BaseModel):
+    """One SHACL finding with the full detail Django
+    gneeds to rebuild a ``ValidationIssue``.
+
+    The generic ``ValidationMessage`` on the output envelope is lossy — it has no
+    ``meta`` (SHACL focus node / source shape / constraint component) and no
+    ``assertion_id`` (SPARQL-ASK attribution). SHACL carries those through this
+    richer per-finding model so Django's ``post_execute_validate`` can reconstruct
+    findings with the same fidelity as the old in-process path.
+
+    ``severity`` is a plain string (ERROR / WARNING / INFO / SUCCESS) rather than
+    the shared ``Severity`` enum because SHACL emits SUCCESS rows for passing
+    SPARQL-ASK assertions with a configured success message, and ``Severity`` only
+    covers INFO/WARNING/ERROR. Django maps it back to its own severity enum.
+    """
+
+    path: str = Field(default="")
+    message: str = Field(description="Human-readable finding text.")
+    severity: str = Field(description="ERROR | WARNING | INFO | SUCCESS.")
+    code: str = Field(default="")
+    meta: dict[str, Any] = Field(default_factory=dict)
+    assertion_id: int | None = Field(default=None)
+
+    model_config = {"extra": "forbid"}
+
+
+class SHACLOutputs(BaseModel):
+    """SHACL validation results and the ``o.*`` signal dict.
+
+    The signal fields (``parse_ok`` … ``shacl_total_count``) mirror the catalog
+    entries declared in the Django SHACL ``ValidatorConfig`` — Django's
+    ``extract_output_signals`` pulls exactly those keys for CEL/Basic assertion
+    evaluation. The remaining fields carry evidence (the serialized report) and
+    the container-side SPARQL-ASK assertion counts.
+    """
+
+    conforms: bool = Field(description="Whether the data graph conforms to the shapes.")
+
+    findings: list[SHACLFinding] = Field(
+        default_factory=list,
+        description=(
+            "Blocking + advisory findings (SHACL results, SPARQL-ASK outcomes, "
+            "bundle/parse/engine messages) with full meta for Django to rebuild "
+            "ValidationIssue rows. Already filtered per shacl_result_handling."
+        ),
+    )
+
+    # ── o.* signals (must stay aligned with the SHACL ValidatorConfig catalog) ──
+    parse_ok: bool = Field(description="Whether the submitted RDF parsed.")
+    parse_serialization: str = Field(description="rdflib format used to parse.")
+    triple_count: int = Field(default=0, ge=0)
+    namespaces_present: list[str] = Field(default_factory=list)
+    has_s223_namespace: bool = Field(default=False)
+    has_g36_namespace: bool = Field(default=False)
+    has_brick_namespace: bool = Field(default=False)
+    shacl_violation_count: int = Field(default=0, ge=0)
+    shacl_warning_count: int = Field(default=0, ge=0)
+    shacl_info_count: int = Field(default=0, ge=0)
+    shacl_total_count: int = Field(default=0, ge=0)
+
+    # ── Evidence + run metadata ──
+    results_graph_turtle: str = Field(
+        default="",
+        description="Serialized sh:ValidationReport (Turtle) for evidence download.",
+    )
+    shacl_shapes_sha256: str = Field(default="")
+    shacl_ontology_sha256: str = Field(default="")
+    advanced_shacl_requested: bool = Field(default=False)
+    shacl_result_handling: str = Field(default="")
+
+    # ── Container-side SPARQL-ASK assertion tallies (folded into AssertionStats) ──
+    assertion_total: int = Field(default=0, ge=0)
+    assertion_failures: int = Field(default=0, ge=0)
+
+    execution_seconds: float = Field(default=0.0, ge=0)
+    pyshacl_version: str | None = Field(default=None)
+
+    model_config = {"extra": "forbid"}
+
+
+class SHACLInputEnvelope(ValidationInputEnvelope):
+    """Input envelope for SHACL validator containers."""
+
+    inputs: SHACLInputs
+
+
+class SHACLOutputEnvelope(ValidationOutputEnvelope):
+    """Output envelope from SHACL validator containers.
+
+    ``outputs`` can be ``None`` for runtime-failure cases where the engine never
+    produced a report (e.g. the submission failed to parse before SHACL ran).
+    """
+
+    outputs: SHACLOutputs | None = None
+
+
+# Default file role/MIME for the submitted RDF graph. The role mirrors the
+# "primary-model" convention used by EnergyPlus; the container reads
+# input_files[0].uri regardless of role.
+_RDF_FORMAT_TO_MIME: dict[str, SupportedMimeType] = {
+    "turtle": SupportedMimeType.RDF_TURTLE,
+    "n3": SupportedMimeType.RDF_TURTLE,
+    "json-ld": SupportedMimeType.RDF_JSON_LD,
+    "xml": SupportedMimeType.RDF_XML,
+    "nt": SupportedMimeType.RDF_N_TRIPLES,
+    "nquads": SupportedMimeType.RDF_N_QUADS,
+}
+
+
+def mime_type_for_rdf_format(rdf_format: str) -> SupportedMimeType:
+    """Map a resolved rdflib format slug to a SupportedMimeType (Turtle default)."""
+    return _RDF_FORMAT_TO_MIME.get(rdf_format, SupportedMimeType.RDF_TURTLE)
+
+
+def build_shacl_input_envelope(
+    *,
+    run_id: str,
+    validator,
+    org_id: str,
+    org_name: str,
+    workflow_id: str,
+    step_id: str,
+    step_name: str | None,
+    submission_uri: str,
+    inputs: SHACLInputs,
+    callback_url: str,
+    execution_bundle_uri: str,
+    callback_id: str | None = None,
+    skip_callback: bool = False,
+) -> SHACLInputEnvelope:
+    """Build a ``SHACLInputEnvelope`` from Django validation data.
+
+    Args:
+        run_id: ValidationRun ID.
+        validator: Validator-like object (id/validation_type/version attrs).
+        org_id / org_name: Organization identity.
+        workflow_id / step_id / step_name: Workflow context.
+        submission_uri: Storage URI for the RDF submission (gs:// or file://).
+        inputs: Fully-resolved ``SHACLInputs`` (shapes/ontology/settings/asks).
+        callback_url: URL the container POSTs to on completion.
+        execution_bundle_uri: Base URI for this run's bundle.
+        callback_id: Idempotency key echoed back in the callback.
+        skip_callback: True for synchronous (Docker) execution.
+    """
+    input_files = [
+        InputFileItem(
+            name="submission.rdf",
+            mime_type=mime_type_for_rdf_format(inputs.rdf_format),
+            role="primary-model",
+            uri=submission_uri,
+        ),
+    ]
+
+    context = ExecutionContext(
+        callback_id=callback_id,
+        callback_url=callback_url,
+        execution_bundle_uri=execution_bundle_uri,
+        skip_callback=skip_callback,
+    )
+
+    return SHACLInputEnvelope(
+        run_id=run_id,
+        validator=ValidatorInfo(
+            id=str(validator.id),
+            type=ValidatorType(validator.validation_type),
+            version=str(getattr(validator, "version", "1")),
+        ),
+        org={"id": org_id, "name": org_name},
+        workflow={
+            "id": workflow_id,
+            "step_id": step_id,
+            "step_name": step_name,
+        },
+        input_files=input_files,
+        inputs=inputs,
+        context=context,
+    )

{validibot_shared-0.8.0 → validibot_shared-0.9.0}/validibot_shared/validations/envelopes.py

@@ -143,6 +143,7 @@ class ValidatorType(str, Enum):
     BASIC = "BASIC"
     JSON_SCHEMA = "JSON_SCHEMA"
     XML_SCHEMA = "XML_SCHEMA"
+    SHACL = "SHACL"
     ENERGYPLUS = "ENERGYPLUS"
     FMU = "FMU"
     CUSTOM_VALIDATOR = "CUSTOM_VALIDATOR"
@@ -173,6 +174,16 @@ class SupportedMimeType(str, Enum):
     # FMU files
     FMU = "application/vnd.fmi.fmu"  # Functional Mock-up Unit
 
+    # RDF serializations (SHACL validator). The concrete parse format is
+    # carried by SHACLInputs.submission_format; these MIME types let the RDF
+    # submission ride the typed InputFileItem.mime_type field like any other
+    # validator input.
+    RDF_TURTLE = "text/turtle"
+    RDF_XML = "application/rdf+xml"
+    RDF_JSON_LD = "application/ld+json"
+    RDF_N_TRIPLES = "application/n-triples"
+    RDF_N_QUADS = "application/n-quads"
+
 
 class InputFileItem(BaseModel):
     """