PRD-008: SHACL Runtime Enforcement and Governance

Type

Functional

Priority

High

MVP Status

⏳ In Progress

Requirement Statement (EARS Format)

As a platform owner, I want SHACL validation to be enforced consistently and safely across contexts, so that knowledge graph integrity is guaranteed while enabling controlled rollout and remediation.

User Story

As the Knowledge Graph Operator, I want to enable SHACL enforcement per context with clear diagnostics and migration guidance, so that I can safely roll out validation without disrupting production.

Acceptance Criteria

AC-008.1: Enforcement Gating

• Given a SHACL validation request
• When enforcement is enabled and the context is active
• Then invalid data shall be rejected with a structured validation error

AC-008.2: Maintenance Mode

• Given SHACL enforcement is enabled
• When maintenance mode is active
• Then violations shall be recorded with error-level logging but shall not raise blocking errors

AC-008.3: Versioned Shapes

• Given a shapes version is configured
• When validation runs
• Then the system shall load sea-shapes.{version}.shacl and fall back to sea-shapes.shacl if missing

AC-008.4: Cross-Context Dependencies

• Given a shape declares sea:requiresContext
• When a referenced context is missing
• Then validation shall surface an explicit missing-context error

AC-008.5: Diagnostics and Fix Guidance

• Given a validation failure
• When a report is generated
• Then the report shall include violated shape URI, focus node, property path, and suggested fixes

AC-008.6: Tooling and Impact Analysis

• Given shapes or data changes
• When impact analysis is run
• Then the system shall report affected entities and violation summaries

Dependencies

• Knowledge Graph Service
• Ontology shapes
• SHACL tooling

Related Specifications

• ADRs: ADR-040, ADR-006
• SDS: SDS-003

Success Metrics

• Percentage of writes validated with SHACL
• Reduction in inconsistent triples
• Mean time to diagnose validation failures