Skip to main content
Version: v0.6

Namespaces

Ory Keto knows the concept of namespaces to organize relation tuples. Namespaces have a configuration that defines the relations, and some other important values (see reference). Unlike other applications, Ory Keto does not isolate namespaces. Especially, subject sets can cross-reference from one namespace to another. The namespaces' purpose is to split up the data into coherent partitions, each with its corresponding configuration. Internally each namespace has its own table in the database to allow setting individual storage specific options.

Scoping of Objects#

The application can also use namespaces to scope objects because Ory Keto only compares objects within a namespace. For example, if Ory Keto knows the following relation tuples

// user1 has acces to the directory foo
directories:foo#access@user1
// user2 has access to the file foo
files:foo#access@user2

both of the following check requests

// Does user2 have access to the directory foo?
directories:foo#access@user2
// Does user1 have access to the file foo?
files:foo#access@user1

will evaluate to false (a.k.a. rejected).

Vice versa, all relation tuples containing an object have to be in the same namespace to reference the same object.

Migrations#

Because namespaces each come with an individual configuration that can even modify some storage specific options, it is required to manually review and run migrations on namespace configuration updates. Please refer to the namespace migration CLI reference and running in production guide to learn more about that process.

Naming Conventions#

Namespaces should be named after the plural of the type of objects they describe (e.g. files, chats, organizations). Relations within a namespace should be a word that describes what relation a subject has towards an object. As a rule of thumb, every relation tuple should translate to an english sentence like so:

Subject has relation on object which is one of the namespace.

Examples:

// good examples
files:8f427c01-c295-44f3-b43d-49c3a1042f35#write@02a3c847-c903-446a-a34f-dae74b4fab86
groups:43784684-103e-44c0-9d6c-db9fb265f617#member@b8d00059-b803-4123-9d3d-b3613bfe7c1b
directories:803a87e9-0da0-486e-bc08-ef559dd8e034#child@(files:11488ab9-4ede-479f-add4-f1379da4ae43#_)
files:11488ab9-4ede-479f-add4-f1379da4ae43#parent@(directories:803a87e9-0da0-486e-bc08-ef559dd8e034#_)
// bad examples
// namespace is not describing homogenous type of objects
tenant-1-objects:62237c27-19c3-4bb1-9cbc-a5a67372569b#access@7a012165-7b21-495b-b84b-cf4e1a21b484
// relation describes a relation of the object towards the subject
directories:803a87e9-0da0-486e-bc08-ef559dd8e034#parent@(files:11488ab9-4ede-479f-add4-f1379da4ae43#_)
Last updated on by Patrik