Namespaces

In Ory Permissions, namespaces fulfill two purposes:

• They are used to scope objects and subjects.
• They contain rules that define which relationships are looked up as part of a permission check.

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