SpiceDB v0.15 introduces stricter validation for undefined caveats in relationship tuples

Question

The goal is to decide how to handle existing relationship tuples that reference caveats not defined in the schema after upgrading to SpiceDB v0.15, where such tuples are now rejected at write time.

Operators must avoid runtime CheckPermission errors caused by the new INVALID_ARGUMENT response, while also considering the effort required to clean up or migrate data before a rolling upgrade.

Uncertainty remains around whether a compatibility mode should be offered to preserve the v0.14 behavior (treating undefined caveats as false) during the transition period, and if so, how it should be configured and what impact it would have on data integrity and future schema evolution.

Should SpiceDB introduce a compatibility mode flag to revert to the v0.14 validation behavior for undefined caveats?
If added, how should the flag be scoped (global, per‑namespace, or per‑tuple) and what are the implications for existing tuples and future writes?
What migration guidance should be provided for administrators who cannot purge invalid tuples before upgrading?

Zoha · Answer

The v0.15 release enforces schema-defined caveats during tuple writes, rejecting any relationship tuple that references a caveat not declared in the current schema. This change prevents inconsistent CheckPermission outcomes but blocks upgrades for clusters holding tuples with undefined caveat references.

Confirmed behavior

SpiceDB v0.15 validates caveat definitions against the schema at write time.
Undefined caveat references cause an INVALID_ARGUMENT validation error.
Earlier versions permitted undefined caveats, which could lead to runtime permission errors.

Transition steps

Use the SpiceDB admin CLI or UI to list tuples and inspect each tuple's caveat references against the active schema definition.
Identify tuples referencing undefined caveats; plan either to define the missing caveats in the schema or to remove/alter the tuples before the rolling upgrade.
If immediate upgrade is required and defining or removing tuples is not feasible, evaluate a compatibility mode flag that reverts to v0.14-style treatment (undefined caveats evaluated as false).

One diagnostic detail will help finalize the recommendation: whether your deployment currently contains any relationship tuples with caveat references not present in the active schema. Confirming this will determine if a compatibility mode flag is the appropriate stopgap or if data cleanup is a prerequisite for a clean v0.15 upgrade.

SpiceDB v0.15 introduces stricter validation for undefined caveats in relationship tuples

1 answer

Confirmed behavior

Transition steps

Your perspective belongs here.

0 question comments