Skip to content

Commit

Permalink
docs: add namespace and relation naming conventions (#510)
Browse files Browse the repository at this point in the history
  • Loading branch information
zepatrik authored Mar 27, 2021
1 parent e3f7ad9 commit dd31865
Showing 1 changed file with 29 additions and 0 deletions.
29 changes: 29 additions & 0 deletions docs/docs/concepts/namespaces.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -49,3 +49,32 @@ 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](/TODO) and
[running in production guide](/TODO) 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:

```keto-relation-tuples
// 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#_)
```

0 comments on commit dd31865

Please sign in to comment.