Reflection APIs

The Experimental Reflection APIs (opens in a new tab) in SpiceDB (starting at version v1.33.0) provide the ability to reflect on the stored schema and type information to answer questions about the schema itself, as well as its permissions and relations.

ExperimentalReflectSchema

ExperimentalReflectSchema provides an API-driven means of receiving the structure of the current schema stored in SpiceDB.

It is designed primarily to allow callers to make dynamic decisions based on the structure of the schema, such as being able to see all the permissions defined for a particular type of resource.

ExperimentalReflectSchemaRequest{}
 
ExperimentalReflectSchemaResponse{
  Definitions: []{
     { Name: "user" },
     {
        Name: "organization",
        Relations: []{
           { Name: "member", SubjectTypes: []{ { Name: "user" } }, ... },
        },
     },
     {
       Name: "resource",
       Comment: "// resource is some kind of resource",
       Relations: []{ ... },
       Permissions: []{ ... },
     },
  },
}

Filtering

ExperimentalReflectSchemaRequest also includes support for filters which can be used to filter the response to a specific subset of the schema:

ExperimentalReflectSchemaRequest{
  OptionalFilters: []{
     {
        OptionalDefinitionNameFilter: "a" // filter to defs starting with `a`
     },
  },
}

ExperimentalDiffSchema

ExperimentalDiffSchema provides an API-driven means of comparing the currently stored schema in SpiceDB to another schema.

This API is useful for tooling such as CI/CD that needs to determine what changes, if any, exist between the current schema and a future schema.

ExperimentalDiffSchema{
  ComparisonSchema: """
    definition user  {}
 
    // an added comment
    definition organization {
      relation member: user
    }
 
    // resource is some kind of resource
    definition resource {
      relation viewer: user
      relation editor: user
 
      relation org: organization
 
      permission edit = editor
      permission view = viewer + editor + org->member
    }
  """
}
 
ExperimentalReflectSchemaResponse{
  Diffs: []{
    { DefinitionDocCommentChanged: { Name: "organization", ... } },
    { PermissionExprChanged: { Name: "view", ... } },
  }
}

ExperimentalDependentRelations

ExperimentalDependentRelations is a reflection API that provides the list of relations and permissions that are used to compute a particular permission.

ExperimentalDependentRelationsRequest{
  DefinitionName: "resource"
  PermissionName: "view"
}
 
ExperimentalDependentRelationsResponse{
  Relations: []{
     { DefinitionName: "organization", RelationName: "member", IsPermission: false},
     { DefinitionName: "resource", RelationName: "org", IsPermission: false},
     { DefinitionName: "resource", RelationName: "viewer", IsPermission: false},
     { DefinitionName: "resource", RelationName: "edit", IsPermission: true},
     { DefinitionName: "resource", RelationName: "editor", IsPermission: false},
  }
}

ExperimentalComputablePermissions

ExperimentalComputablePermissions is the inverse of ExperimentalDependentRelations: it helps to determine any permissions impacted by a change to a relation or permission.

ExperimentalComputablePermissionsRequest{
  DefinitionName: "resource"
  RelationName: "viewer"
}
 
ExperimentalComputablePermissionsResponse{
  Permissions: []{
    { DefinitionName: "resource", RelationName: "view", IsPermission: true},
  }
}

Relationship Caveats Schema Language