feat: support for rel and namespace deprecation #2504

kartikaysaxena · 2025-07-21T17:31:37Z

This PR adds support for relation and namespace level deprecation in schemas.

Relations and namespaces can now be annotated with a @deprecated(...) directive to indicate they are deprecated.
When a relationship is written to a deprecated relation or deprecated namespace:
- A warning or error is generated, depending on the specified deprecation level.
- In the current implementation, writes fail when an error deprecation is configured.
Deprecation is associated with the definition/relation decorated with the deprecation.
A flag is to be passed to enable this feature, namely --enable-experimental-deprecation along with use directive.

Example:

use deprecation

@deprecated(warn, "comments")
definition user {}

definition resource {
  relation viewer: user | @deprecated(warn, "documents can no longer be public") user:*

  @deprecated(error, "comment goes here")
  relation admin: user
}

Note

Each relation has a object Deprecation assigned to them containing an enum DeprecationType and optional comments, if unspecified DeprecationType defaults to DEPRECATED_TYPE_UNSPECIFIED

Note

Attempted write with a DELETE operation to a deprecated relation/namespace doesn't fail

(related #2465)

codecov · 2025-07-21T17:33:44Z

Codecov Report

❌ Patch coverage is 86.18090% with 55 lines in your changes missing coverage. Please review.
✅ Project coverage is 79.47%. Comparing base (d4ff660) to head (d98c374).

Files with missing lines	Patch %	Lines
pkg/schema/typesystem.go	74.60%	19 Missing and 12 partials ⚠️
pkg/schemadsl/compiler/translator.go	78.79%	8 Missing and 6 partials ⚠️
pkg/schemadsl/parser/parser.go	75.00%	6 Missing and 3 partials ⚠️
pkg/schemadsl/generator/generator.go	97.37%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2504      +/-   ##
==========================================
+ Coverage   79.46%   79.47%   +0.02%     
==========================================
  Files         456      456              
  Lines       47322    47664     +342     
==========================================
+ Hits        37600    37877     +277     
- Misses       6963     7004      +41     
- Partials     2759     2783      +24

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

internal/services/server.go

josephschorr · 2025-07-21T17:40:45Z

internal/services/shared/errors.go

+		err,
+		codes.Aborted,
+		spiceerrors.ForReason(
+			v1.ErrorReason_ERROR_REASON_SCHEMA_TYPE_ERROR,


Add a new error reason into the API and use it here

just raising that into the api repo, once that gets in, i will switch to that

here: authzed/api#143

Add a TODO here

internal/services/shared/errors.go

josephschorr · 2025-07-21T17:43:23Z

internal/services/v1/relationships.go

+		return err
+	}
+	reader := ds.SnapshotReader(headRevision)
+	_, relDef, err := namespace.ReadNamespaceAndRelation(ctx, resource.ObjectType, update.Relationship.Relation, reader)


rather than reading the namespace again, let's do this check in the existing validation block, just as an additional check if enabled

migrated the check to the relationship validation block to remove unnecessary lookups, also this now uses the typesystem for the read, also added a test

Can we add a method into the type system to retrieve the deprecation status of a namespace and/or relation and then use that? Its good to have it in a single place

josephschorr · 2025-07-21T17:43:48Z

internal/services/v1/relationships.go

+		return err
+	}
+
+	if relDef.Deprecation != nil && relDef.Deprecation.DeprecationType != corev1.DeprecationType_DEPRECATED_TYPE_UNSPECIFIED {


I think you can add deprecation to the type system and just read it from there

ecordell · 2025-07-21T18:52:44Z

Just thinking about the UX a bit (we don't have to solve it in this PR - just thinking ahead!) it would be nice to be able to do something like:

definition document {
  relation viewer: user

  @deprecated(warn, "documents can no longer be public")
  relation viewer: user:*
}

which would normally fail validation as a duplicated relation name

josephschorr · 2025-07-21T19:14:29Z

Just thinking about the UX a bit (we don't have to solve it in this PR - just thinking ahead!) it would be nice to be able to do something like:
definition document {
  relation viewer: user

  @deprecated(warn, "documents can no longer be public")
  relation viewer: user:*
}
which would normally fail validation as a duplicated relation name

Not sure... I kind of prefer:

relation viewer: user | @deprecated(warn, "documents can no longer be public") user:*

kartikaysaxena · 2025-07-21T20:09:07Z

Just thinking about the UX a bit (we don't have to solve it in this PR - just thinking ahead!) it would be nice to be able to do something like:
definition document {
  relation viewer: user

  @deprecated(warn, "documents can no longer be public")
  relation viewer: user:*
}
which would normally fail validation as a duplicated relation name
Not sure... I kind of prefer:
relation viewer: user | @deprecated(warn, "documents can no longer be public") user:*

this would require extending the support to the type reference, would look into that, or address do that in a follow up

josephschorr · 2025-07-22T17:29:26Z

Just thinking about the UX a bit (we don't have to solve it in this PR - just thinking ahead!) it would be nice to be able to do something like:
definition document {
  relation viewer: user

  @deprecated(warn, "documents can no longer be public")
  relation viewer: user:*
}
which would normally fail validation as a duplicated relation name
Not sure... I kind of prefer:
relation viewer: user | @deprecated(warn, "documents can no longer be public") user:*
this would require extending the support to the type reference, would look into that, or address do that in a follow up

Followup is fine

kartikaysaxena · 2025-07-22T17:35:31Z

Just thinking about the UX a bit (we don't have to solve it in this PR - just thinking ahead!) it would be nice to be able to do something like:
definition document {
  relation viewer: user

  @deprecated(warn, "documents can no longer be public")
  relation viewer: user:*
}
which would normally fail validation as a duplicated relation name
Not sure... I kind of prefer:
relation viewer: user | @deprecated(warn, "documents can no longer be public") user:*
this would require extending the support to the type reference, would look into that, or address do that in a follow up
Followup is fine

I added it just a while ago 😅, have added tests too, if anything looks sideways, would revert back to previous commit, or if any other suggestion is taken into consideration regarding the type ref approach for relation deprecation, let me know.

kartikaysaxena · 2025-07-22T17:32:26Z

internal/relationships/validation.go

+	for _, allowed := range relDef.TypeInformation.AllowedDirectRelations {
+		// check namespace
+		if allowed.Namespace != rel.Subject.ObjectType {


this iterates over the allowed relation types for a relation to validate the deprecation type, it now supports relation viewer: user | @deprecated(warn, "documents can no longer be public") user:*, also added tests for it.

kartikaysaxena · 2025-07-22T20:15:19Z

pkg/schema/typesystem.go

+	for _, allowed := range rel.TypeInformation.GetAllowedDirectRelations() {
+		// check namespace match


could've used ts.GetFullRecursiveSubjectTypesForRelation() but that too would've took O(N) time and would want a *core.AllowedRelation at other steps as it gives the string types only

kartikaysaxena · 2025-07-23T10:03:02Z

internal/relationships/validation.go

+	for _, update := range updates {
+		if update.Operation == tuple.UpdateOperationTouch || update.Operation == tuple.UpdateOperationCreate {
+			relsToCheck = append(relsToCheck, update.Relationship)
+		}
+	}
+	if err := CheckDeprecationsOnRelationships(ctx, relsToCheck, ts); err != nil {


a little check here as we would not want an attempted write with DELETE operation to a deprecated relation or namespace to fail

kartikaysaxena · 2025-07-23T10:04:00Z

internal/relationships/validation.go

+func checkForDeprecatedRelationsAndObjects(ctx context.Context, rel tuple.Relationship, ts *schema.TypeSystem) error {
+	// Validate if the resource relation is deprecated


this now uses the typesystem with relevant functions

josephschorr · 2025-07-26T16:49:21Z

internal/relationships/validation.go

+		switch relDep.DeprecationType {
+		case core.DeprecationType_DEPRECATED_TYPE_WARNING:
+			log.Warn().
+				Str("namespace", rel.Resource.ObjectType).


namespace -> resource_type

josephschorr · 2025-07-26T16:50:09Z

internal/relationships/validation.go

+	}
+
+	// Validate if the resource namespace is deprecated
+	resDep, ok, err := ts.GetDeprecationForNamespace(ctx, rel.Resource.ObjectType)


GetDeprecationForObjectType

josephschorr · 2025-07-26T16:50:29Z

internal/relationships/validation.go

+		return err
+	}
+	if ok {
+		switch subDep.DeprecationType {


make this "warning vs error" into a helper method and use here and the other two locations

josephschorr · 2025-07-26T16:51:07Z

internal/relationships/validation.go

+
+	// check deprecation for allowed relation types
+	dep, ok, err := ts.GetDeprecationForAllowedRelation(
+		ctx,


might be worth having a method GetDeprecationForRelationship and have it return an error/warning message and what kind it is, if any

but a single relationship might have multiple deprecations (a warning type deprecation at the resource or relation level, and an error type deprecation at the subject level) and it might be necessary to preserve all of them

these methods would now be invoked in CheckRelationshipDeprecation, does this sound about right?

josephschorr · 2025-07-26T16:51:31Z

internal/relationships/validation_test.go

+			}`,
+			"document:foo#editor@testuser:tom",
+			core.RelationTupleUpdate_CREATE,
+			"the relation document#editor is deprecated: deprecated, migrate away",


drop the the, its cleaner :) - relation ....

josephschorr · 2025-07-26T16:51:44Z

internal/services/shared/errors.go

+		err,
+		codes.Aborted,
+		spiceerrors.ForReason(
+			v1.ErrorReason_ERROR_REASON_SCHEMA_TYPE_ERROR,


Add a TODO here

josephschorr · 2025-07-26T16:52:16Z

internal/services/shared/errors.go

+
+func NewDeprecationError(namespace, relation, comments string) DeprecationError {
+	switch {
+	case relation == "*":


use the string method in the type system to describe the relation: you need to handle wildcards, expiration and caveats, and all should be done in there

josephschorr · 2025-07-26T16:52:43Z

internal/relationships/validation_test.go

+		},
+		{
+			"deprecated relation same subject type with wildcard",
+			`use deprecation


add tests for deprecation of, say, a subject type without expiration but the one with expiration is still valid (and vice versa) and caveats as well

added tests of these scenarios including the log and err messages, example "resource_type user with caveat somecaveat and expiration is deprecated:comments here"

josephschorr · 2025-07-26T16:53:18Z

pkg/schema/typesystem.go

 }

+// GetValidatedDefinition looks up and returns a definition struct, if it has been validated.
+func (ts *TypeSystem) GetDeprecationForNamespace(ctx context.Context, definition string) (*core.Deprecation, bool, error) {


Add these methods to the type system tests

josephschorr · 2025-07-26T16:53:46Z

pkg/schemadsl/generator/generator.go

 	sg.markNewScope()

 	for _, relation := range namespace.Relation {
+		if relation.Deprecation != nil && relation.Deprecation.DeprecationType != core.DeprecationType_DEPRECATED_TYPE_UNSPECIFIED {


extra into a helper method

josephschorr · 2025-07-26T16:55:01Z

proto/internal/core/v1/core.proto

+  /**
+   * deprecation contains the required deprecation for the relation.
+   */
+  Deprecation required_deprecation = 8;


This should not be marked as required. The required above means that a caveat (or expiration) must be specified when using the type as part of a subject, which doesn't apply here

kartikaysaxena · 2025-07-27T18:02:26Z

pkg/schema/typesystem.go

+func (ts *TypeSystem) CheckRelationshipDeprecation(ctx context.Context, relationship tuple.Relationship) error {
+	// Validate if the resource relation is deprecated


this method is now invoked during validation of the relationship being written, and is responsible for checking any applicable deprecations on the resource, relation, or subject

kartikaysaxena · 2025-07-27T18:05:05Z

pkg/schema/typesystem.go

+func (ts *TypeSystem) GetDeprecationForAllowedRelation(
+	ctx context.Context,
+	resourceNamespace string,
+	resourceRelation string,
+	subjectNamespace string,
+	subjectRelation string,
+	isWildcard bool,
+	hasCaveat bool,
+	hasExpiration bool,
+) (*core.Deprecation, bool, error) {


this now checks whether the allowed relation reference has a caveat/expiration or both

Might be worth changing this to take in a traits map

kartikaysaxena · 2025-07-30T21:59:38Z

Rebased and updated

josephschorr · 2025-07-31T13:11:47Z

internal/relationships/validation.go

 	}

+	// check if the relation is deprecated for create or touch operations
+	var relsToCheck []tuple.Relationship


relsToCheck := make([]tuple.Relationship, 0, len(updates))

yeah would improve perf, done

josephschorr · 2025-07-31T13:18:22Z

internal/relationships/validation.go

 		len(relationship.OptionalCaveat.Context.GetFields()) > 0
 }
+
+// CheckDeprecationsOnRelationships checks the provided relationships for any deprecations.


// CheckDeprecationsOnRelationships checks the provided relationships for any deprecations, returning an error if applicable

josephschorr · 2025-07-31T13:19:30Z

internal/services/shared/errors.go

+	)
+}
+
+func NewDeprecationError(err error) DeprecationError {


object type, relation, or allowed subject type

josephschorr · 2025-07-31T13:20:04Z

internal/services/shared/errors.go

+	)
+}
+
+func NewDeprecationError(err error) DeprecationError {


Also: can we add a test such that if an object type is deprecated, and you attempt to write with it as a subject, it also fails?

josephschorr · 2025-07-31T13:20:37Z

pkg/schema/definition_test.go

 						require.True(t, traits.AllowsCaveats)
 						require.True(t, traits.AllowsExpiration)

 						_, err = vts.PossibleTraitsForSubject("unknown", "user")


add calls to the deprecation methods in the other tests here, and make sure they all return false/nil/empty

josephschorr · 2025-07-31T13:21:15Z

pkg/schema/typesystem.go

+func (ts *TypeSystem) GetDeprecationForAllowedRelation(
+	ctx context.Context,
+	resourceNamespace string,
+	resourceRelation string,
+	subjectNamespace string,
+	subjectRelation string,
+	isWildcard bool,
+	hasCaveat bool,
+	hasExpiration bool,
+) (*core.Deprecation, bool, error) {


Might be worth changing this to take in a traits map

josephschorr · 2025-07-31T13:21:52Z

pkg/schema/typesystem.go

+		case *core.AllowedRelation_Relation:
+			if isWildcard || w.Relation != subjectRelation {
+				continue
+			}


add a default here that returns a spiceerrors

josephschorr · 2025-07-31T13:22:27Z

pkg/schemadsl/compiler/translator.go

 	if len(relationsAndPermissions) == 0 {
-		ns := namespace.Namespace(nspath)
+		var ns *core.NamespaceDefinition
+		if slices.Contains(tctx.enabledFlags, "deprecation") && slices.Contains(tctx.allowedFlags, "deprecation") && (deprecationForNamespace != &core.Deprecation{}) {


move if slices.Contains(tctx.enabledFlags, "deprecation") && slices.Contains(tctx.allowedFlags, "deprecation") && (deprecationForNamespace != &core.Deprecation{}) into a helper method

barakmich · 2025-07-31T21:51:17Z

pkg/schema/typesystem.go

+}
+
+// CheckRelationshipDeprecation performs a check over the deprecated relationship's resource, relation, subject and allowed relation, if any
+func (ts *TypeSystem) CheckRelationshipDeprecation(ctx context.Context, relationship tuple.Relationship) error {


A related call to this might also be useful in Validate() (in this package) if the deprecation is an error state.

The Validate function is also invoked during WriteSchema, so if we call this in Validate, any attempt to write a schema with this feature containing deprecated resources/relations/subjects would result in an error at schema write time.

kartikaysaxena · 2025-08-05T15:07:27Z

checking on this

josephschorr · 2025-09-15T14:00:41Z

@kartikaysaxena Sorry, I thought this merged. Can you rebase and resolve conflicts?

josephschorr · 2025-10-16T17:14:32Z

@kartikaysaxena Checking in on this; I'd like to get it in but it has conflicts

Signed-off-by: Kartikay <[email protected]>

kartikaysaxena · 2025-11-04T13:41:58Z

Hey @josephschorr sorry was busy at work; I have rebased and resolved the the merge conflicts and did a sanity on the changes. Let me know if anything else is needed, happy to help.

kartikaysaxena requested a review from a team as a code owner July 21, 2025 17:31

kartikaysaxena mentioned this pull request Jul 21, 2025

feat: support relation and object deprecation #2465

Closed

github-actions bot added area/cli Affects the command line area/schema Affects the Schema Language area/api v1 Affects the v1 API area/tooling Affects the dev or user toolchain (e.g. tests, ci, build tools) labels Jul 21, 2025

josephschorr reviewed Jul 21, 2025

View reviewed changes

kartikaysaxena force-pushed the deprecated-objects-rels branch 2 times, most recently from b5137fc to 1ea5e0f Compare July 21, 2025 19:57

kartikaysaxena force-pushed the deprecated-objects-rels branch from 1ea5e0f to 9ce1eed Compare July 22, 2025 17:11

kartikaysaxena requested a review from josephschorr July 22, 2025 17:36

kartikaysaxena force-pushed the deprecated-objects-rels branch from 9ce1eed to f20b462 Compare July 22, 2025 20:02

kartikaysaxena commented Jul 22, 2025

View reviewed changes

kartikaysaxena force-pushed the deprecated-objects-rels branch from f20b462 to b00779f Compare July 23, 2025 10:01

kartikaysaxena commented Jul 23, 2025

View reviewed changes

kartikaysaxena force-pushed the deprecated-objects-rels branch 3 times, most recently from 7419d6f to 3a5f4d4 Compare July 24, 2025 18:54

josephschorr reviewed Jul 26, 2025

View reviewed changes

kartikaysaxena force-pushed the deprecated-objects-rels branch from 3a5f4d4 to 47cda83 Compare July 27, 2025 17:55

kartikaysaxena commented Jul 27, 2025

View reviewed changes

kartikaysaxena force-pushed the deprecated-objects-rels branch 2 times, most recently from bb31fc5 to f0bc6ff Compare July 27, 2025 18:35

josephschorr reviewed Jul 31, 2025

View reviewed changes

barakmich reviewed Jul 31, 2025

View reviewed changes

kartikaysaxena force-pushed the deprecated-objects-rels branch from 7f1a1d8 to 1b3efa7 Compare August 2, 2025 11:51

kartikaysaxena requested a review from josephschorr August 2, 2025 16:25

kartikaysaxena force-pushed the deprecated-objects-rels branch from 1b3efa7 to 5b6d6ac Compare August 5, 2025 17:42

github-actions bot added area/docs Affects docs or metadata (e.g. README) area/datastore Affects the storage system area/dependencies Affects dependencies area/dispatch Affects dispatching of requests area/api http Affects the HTTP Gateway API labels Sep 20, 2025

kartikaysaxena force-pushed the deprecated-objects-rels branch from 0da1a6a to c9be2e2 Compare September 20, 2025 12:40

github-actions bot removed area/docs Affects docs or metadata (e.g. README) area/datastore Affects the storage system area/dependencies Affects dependencies area/dispatch Affects dispatching of requests area/api http Affects the HTTP Gateway API labels Sep 20, 2025

kartikaysaxena force-pushed the deprecated-objects-rels branch 3 times, most recently from d0c7c28 to 3408bfa Compare September 20, 2025 14:14

kartikaysaxena added 2 commits November 4, 2025 14:23

feat: support for rel and namespace deprecation

5f362b4

Signed-off-by: Kartikay <[email protected]>

fix: merge conflict and lint

4b34197

Signed-off-by: Kartikay <[email protected]>

kartikaysaxena force-pushed the deprecated-objects-rels branch 2 times, most recently from 6043dc8 to 36e4276 Compare November 4, 2025 12:16

fix: test

d98c374

Signed-off-by: Kartikay <[email protected]>

kartikaysaxena force-pushed the deprecated-objects-rels branch from 36e4276 to d98c374 Compare November 4, 2025 12:24

		for _, allowed := range rel.TypeInformation.GetAllowedDirectRelations() {
		// check namespace match

		func checkForDeprecatedRelationsAndObjects(ctx context.Context, rel tuple.Relationship, ts *schema.TypeSystem) error {
		// Validate if the resource relation is deprecated

		func (ts *TypeSystem) CheckRelationshipDeprecation(ctx context.Context, relationship tuple.Relationship) error {
		// Validate if the resource relation is deprecated

feat: support for rel and namespace deprecation #2504

Are you sure you want to change the base?

feat: support for rel and namespace deprecation #2504

Uh oh!

Conversation

kartikaysaxena commented Jul 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov bot commented Jul 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kartikaysaxena Jul 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ecordell commented Jul 21, 2025

Uh oh!

josephschorr commented Jul 21, 2025

Uh oh!

kartikaysaxena commented Jul 21, 2025

Uh oh!

josephschorr commented Jul 22, 2025

Uh oh!

kartikaysaxena commented Jul 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kartikaysaxena Jul 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

kartikaysaxena commented Jul 21, 2025 •

edited

Loading

codecov bot commented Jul 21, 2025 •

edited

Loading

kartikaysaxena Jul 21, 2025 •

edited

Loading

kartikaysaxena commented Jul 22, 2025 •

edited

Loading

kartikaysaxena Jul 27, 2025 •

edited

Loading

kartikaysaxena Jul 27, 2025 •

edited

Loading