Removing a relation before clearing references can leave permissions depending on data that no longer has a valid schema path. The article recommends first updating permissions to stop referencing the relation, then deleting the stored relationships, and only after that removing the relation from the definition. That sequence preserves rollback safety.
Why the sequence matters in SpiceDB schema changes
Removing a relation too early breaks the contract between the schema and the data that still depends on it. In SpiceDB, permissions can continue to reference stored relationships until those references are removed, so deleting the relation first creates a gap where existing data has nowhere valid to resolve.
That is why the safe order is to change the permission logic first, then delete the stored relationships, and only then remove the relation from the definition. It is a schema migration problem, not just a cleanup task, and the ordering determines whether the system can still evaluate access cleanly during the transition.
The practical issue is that authorization checks must remain interpretable while the system is in flight. If the relation disappears before the permission graph stops depending on it, the check path can no longer follow a valid schema reference, which makes the old data effectively orphaned from the access model.
This is also why rollback safety depends on preserving the old path until the dependency chain is cleared. If you remove the relation prematurely, reverting the permission change is harder because the schema no longer contains the structure needed to reattach the existing relationships without a repair step.
Failure modes during schema and relationship cleanup
The most immediate failure mode is broken permission evaluation for any object that still has relationships written against the removed relation. Even if the stored data is unchanged, the authorization layer can no longer interpret it as intended, so access decisions become inconsistent with the previous state.
Another failure mode is partial migration drift. Teams may update the permission definition in one release but delete relationships or schema references in another, which leaves a temporary state where some data has been migrated and some has not. That creates ambiguity during deployment, rollback, and incident response.
For this kind of change, the safe pattern is to treat the schema and the stored relationships as coupled state. The relation is not just a label in the model, it is part of the live path that lets permissions resolve against persisted authorization data. If that path is removed before the data is drained, the model and the storage state diverge.
Operationally, that means you need a release plan that preserves evaluability at every step. Teams should assume that any live relationship may still be queried until they have proven that no permission still references it and no stored rows depend on it.
Standards & Framework Alignment
This section maps relevant standards and security frameworks to the operational risks and controls described in this guidance.
CIS Controls v8 and NIST CSF 2.0 set the governance and control requirements practitioners need to meet.
| Framework | Control / Reference | Relevance |
|---|---|---|
| CIS Controls v8 | CIS Control 4 — Secure Configuration of Enterprise Assets and Software | Schema change sequencing is a secure configuration control issue. |
| Recommendation — Treat schema deletions as controlled configuration changes and verify dependencies before removal. | ||
| NIST CSF 2.0 | PR.IP-1 — Identity Management, Authentication, and Access Control Policy and Process | The change affects how access policy is enforced through the schema path. |
| GV.PO-1 — Policies, Processes, and Procedures | Safe removal depends on an explicit change procedure and rollback order. | |
| Recommendation — Update access-control logic before removing dependent schema elements. Define a release procedure that sequences permission updates, data cleanup, then schema deletion. | ||
Practitioner Guidance
What to verify: Confirm that no active permission still points at the relation before you delete stored relationships. The right validation is not just “the new schema deploys,” but “the old path is no longer reachable in evaluation.”
Implementation sequence: 1) remove the relation from permissions, 2) remove or drain the stored relationships, 3) delete the relation from the schema definition. That order keeps rollback options open and avoids orphaned authorization data.
Common mistake: Treating relation deletion as a harmless cleanup step after the code change. In practice, it is the last step in a dependency cleanup, not the first.
Practitioner takeaway: If a relation still has live references, deleting it is a breaking change to authorization state, so migration order matters as much as the final schema.
Related resources from NHI Mgmt Group
Deepen Your Knowledge
Reviewed and updated by the NHIMG editorial team on September 17, 2026.
NHI Mgmt Group — the #1 independent authority on Non-Human Identity, IAM, and Agentic AI security. nhimg.org
