Proposal: Treat SHACL Shapes as Immutable

[tgra]

Context

In Solid, SHACL shapes function as interoperability contracts between:

• Applications
• User data storage Pods
• Semantic vocabularies

Validation schemas are widely consumed and may be cached by clients.

Decision

Shapes in the catalogue should be treated as immutable artefacts once published.

Changes to validation logic should always be introduced via:

• New shapes
• New namespaces

Rationale

Prevents Breaking Decentralised Clients

Solid applications may:

• Ship validation logic locally
• Cache shapes
• Operate offline

Modifying shapes after release could cause inconsistent behaviour.

Supports Long-Term Data Interoperability

Solid's decentralised ecosystem requires stable contracts to allow independent development.

Enables Predictable Governance

Immutability simplifies:

• Review processes
• Security auditing
• Compliance validation

Alternatives Considered

Mutable Shape Definitions

Rejected because:

• Creates silent interoperability failures
• Makes Pod data validation unpredictable

File-Level Versioning Only

Partial solution but insufficient because clients may reference specific shape IRIs.

Implementation Recommendations

Adopt:

Namespaces

When a breaking change to a shape is required, the existing shape must remain unchanged and a new shape with a new namespace IRI should be created in the same domain file.

Example:

• https://solid.github.io/shapes/address#AddressShape
• https://solid.github.io/shapes/address#AddressShapeV2

Shape Publishing Rules

Once merged:

• Shapes are considered frozen
• New behaviour must be introduced via new IRIs

Optional Metadata Extensions

Allowed:

• sh:description
• sh:comment
• sh:example

Not allowed post-release:

• Structural rule changes

Governance Status

• Shape rule changes — Require creation of a new shape
• Optional property additions — Allowed
• Cardinality or class changes — Not allowed after release

[tgra]

seeking review of this please @jeswr @langsamu

[jeswr]

I think this is a good idea; and we should:

• Be opinionated on naming convention.
• Use metadata properties outlined here to reference the next version. This makes it easier - for instance - to create CI which will create versioned npm packages rather than distinct libraries for each version of an artefact.