---
id: namespaces
title: Namespaces in Ory Permissions
sidebar_label: Namespaces
---

# Namespaces

In Ory Permissions, namespaces fulfill two purposes:

- They are used to scope [objects](./10_objects.mdx) and [subjects](./15_subjects.mdx).
- They contain rules that define which [relationships](./01_relation-tuples.mdx) are looked up as part of a permission check.

[Relationships](./01_relation-tuples.mdx) 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:

```ts
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:

```keto-natural
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](../modeling/create-permission-model.mdx).

:::

## 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](https://wiki.c2.com/?UpperCamelCase), 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:

```keto-natural
<Subject> is in <relation> of <Object>
```

Relationships are like the edges in a graph connecting subjects and objects. These edges are always
[many-to-many relationships](<https://en.wikipedia.org/wiki/Many-to-many_(data_model)>) so the relationship should be in plural
form.

### Examples

- Correct naming ✅

  ```keto-natural
  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 ❌

  ```keto-natural
  // 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
  ```