SHACL Shape Versioning Guide

Compatibility Policy

• Backward compatibility applies to minor/patch increments only (vN.x supports shapes from vN.(x-1)).
• Major versions introduce breaking changes (e.g., removing/renaming shape targets, changing required paths/cardinality, or restructuring shape graphs).
• Follow semantic versioning (major.minor.patch): compatible change example v1.2 → v1.3, breaking change example v1.9 → v2.0.

Creating a New Version

1. Copy the existing shapes file:
   • ontologies/sea-shapes.vN.shacl -> ontologies/sea-shapes.vN+1.shacl
2. Update constraints and imports.
3. Run impact analysis:
   • python tools/shape_impact_analysis.py --shape-version vN+1 --graph <snapshot|ttl|nt>
   • Use shape_impact_analysis.py for new-shape iterations; use kg_validate.py to validate a deployed SHACL_SHAPES_VERSION.
4. Validate in staging with:
   • SHACL_SHAPES_VERSION=vN+1

Rollout Strategy

• Deploy shapes file (copy to shared volume or update ConfigMap/CI artifact), then restart affected services to reload shapes.
• Enable dual validation in staging:
  • Validate incoming data against both old and new shapes.
  • Log and surface schema diffs, mismatch counts, and failure categories.
• Monitor rollout metrics via dashboards/alerts:
  • Validation failure rate, error rate, latency impact, resource usage, logging volume.
• Promotion criteria:
  • Failure rate <1% for N days or X stable transactions (define per environment).
  • No sustained latency regression (>10% p95) during the observation window.
• Rollback triggers and procedure:
  • Immediate rollback if failure rate spikes above threshold or latency breaches.
  • Revert ConfigMap/volume to last known good shapes and restart services.
  • Require architecture approval for shared shapes; domain owner approval for bounded-context shapes.
  • Reference deployment and monitoring runbooks for exact steps (docs/handbooks/Document_Operations_Handbook/shacl-enforcement-migration.md).

Change Notifications

• Emit a ShapeVersionChanged event on startup
• Include breaking change flags and affected contexts

Rollback

• Revert SHACL_SHAPES_VERSION to the last known good version (identify via version tags, CI artifacts, or a “stable” pointer).
• Restart affected services so the previous shapes are loaded.
• Run python tools/kg_validate.py with the reverted SHACL_SHAPES_VERSION to confirm baseline integrity.
• Archive the problematic shapes file by default (remove only if explicitly approved).
• If data was migrated to conform to the new shapes, plan data reverse-migration or cleanup.
• Notify stakeholders, document rollback reason, timeline, and impact.