Skip to main content

Namespaces

In Ory Permissions, namespaces fulfill two purposes:

Relationships can reference different namespaces. For example, a user (from the User namespace) can have access to a file (from the Document namespace).

Definition​

In the Ory Permission Language, namespaces are defined as follows:

import { Namespace, Context } from "@ory/keto-namespace-types"

class User implements Namespace {}
class Document implements Namespace {}
class Folder implements Namespace {}

Each namespace holds a set of permissions, which define which relationships are checked. For example, checking a view permission for User:bob on an readme.txt file in the Document namespace requires the following relationship lookups:

is User:bob in viewers of Document:readme.txt // all viewers can view the document
is User:bob in editors of Document:readme.txt // all editors can view the document
is User:bob in owners of Document:readme.txt // all owners can view the document

The permission model defines which relationships are checked in the process.

tip

Learn how to create a permission model.

Naming conventions​

Namespaces​

As namespaces are defined as TypeScript classes in the Ory Permission Language, they should be named after the singular form of the type they describe. The name should be in upper camel case, for example: User,Document, Folder, AccessKey.

Relationships​

Relationships in a namespace should be named with a plural form word that describes what relation a subject has with an object. Every relationship should translate to an English sentence, for example:

Subject is in members of Object

Relationships are like the edges in a graph connecting subjects and objects. These edges are always many-to-many relationships so the relationship should be in plural form.

Examples​

  • Correct naming ✅

    User:02a3c847-c903-446a-a34f-dae74b4fab86 is in writers of File:8f427c01-c295-44f3-b43d-49c3a1042f35
    User:b8d00059-b803-4123-9d3d-b3613bfe7c1b is in members of Group:43784684-103e-44c0-9d6c-db9fb265f617
    File:11488ab9-4ede-479f-add4-f1379da4ae43 is in children of Directory:803a87e9-0da0-486e-bc08-ef559dd8e034
    Directory:803a87e9-0da0-486e-bc08-ef559dd8e034 is in parents of File:11488ab9-4ede-479f-add4-f1379da4ae43

  • Incorrect naming ❌

    // namespace isn't describing homogenous type of objects
    User:7a012165-7b21-495b-b84b-cf4e1a21b484 is in members of Tenant1Objects:62237c27-19c3-4bb1-9cbc-a5a67372569b

    // Does not adhere to the naming conventions
    users:02a3c847-c903-446a-a34f-dae74b4fab86 is in view of files:8f427c01-c295-44f3-b43d-49c3a1042f35