> ## Documentation Index > Fetch the complete documentation index at: https://proxy-docs.permify.co/llms.txt > Use this file to discover all available pages before exploring further. # Organization Tool This is a schema definition of the authorization model for Notion, a popular productivity and organization tool. ### Schema | [Open in playground](https://play.permify.co/?s=BsCvLmd4g81sB20XJZI5p) ```perm theme={null} entity user {} entity workspace { // The owner of the workspace relation owner @user // Members of the workspace relation member @user // Guests (users with read-only access) of the workspace relation guest @user // Bots associated with the workspace relation bot @user // Admin users who have permission to manage the workspace relation admin @user // Define permissions for workspace actions permission create_page = owner or member or admin permission invite_member = owner or admin permission view_workspace = owner or member or guest or bot permission manage_workspace = owner or admin // Define permissions that can be inherited by child entities permission read = member or guest or bot or admin permission write = owner or admin } entity page { // The workspace associated with the page relation workspace @workspace // The user who can write to the page relation writer @user // The user(s) who can read the page (members of the workspace or guests) relation reader @user @workspace#member @workspace#guest // Define permissions for page actions permission read = reader or workspace.read permission write = writer or workspace.write } entity database { // The workspace associated with the database relation workspace @workspace // The user who can edit the database relation editor @user // The user(s) who can view the database (members of the workspace or guests) relation viewer @user @workspace#member @workspace#guest // Define permissions for database actions permission read = viewer or workspace.read permission write = editor or workspace.write permission create = editor or workspace.write permission delete = editor or workspace.write } entity block { // The page associated with the block relation page @page // The database associated with the block relation database @database // The user who can edit the block relation editor @user // The user(s) who can comment on the block (readers of the parent object) relation commenter @user @page#reader // Define permissions for block actions permission read = database.read or commenter permission write = editor or database.write permission comment = commenter } entity comment { // The block associated with the comment relation block @block // The author of the comment relation author @user // Define permissions for comment actions permission read = block.read permission write = author } entity template { // The workspace associated with the template relation workspace @workspace // The user who creates the template relation creator @user // The user(s) who can view the page (members of the workspace or guests) relation viewer @user @workspace#member @workspace#guest // Define permissions for template actions permission read = viewer or workspace.read permission write = creator or workspace.write permission create = creator or workspace.write permission delete = creator or workspace.write } entity integration { // The workspace associated with the integration relation workspace @workspace // The owner of the integration relation owner @user // Define permissions for integration actions permission read = workspace.read permission write = owner or workspace.write } ``` ## Brief Examination of the Model The model defines several entities, including users, workspaces, pages, databases, blocks, and integrations. It also includes several default roles, such as Admin, Bot, Guest, and Member. Here's a breakdown of the entities: ### Entities & Relations * **`user`**: Represents a user in the system. * **`workspace`**: Represents a workspace in which users can collaborate. Each workspace has an owner, members, guests, and bots associated with it. The owner and admin users have permission to manage the workspace. Permissions are defined for creating pages, inviting members, viewing the workspace, and managing the workspace. The read and write permissions can be inherited by child entities. * **`page`**: Represents a page within a workspace. Each page is associated with a workspace and has a writer and readers. The read and write permissions are defined based on the writer and readers of the page and can be inherited from the workspace. * **`database`**: Represents a database within a workspace. Each database is associated with a workspace and has an editor and viewers. The read and write permissions are defined based on the editor and viewers of the database and can be inherited from the workspace. Permissions are also defined for creating and deleting databases. * **`block`**: Represents a block within a page or database. Each block is associated with a page or database and has an editor and commenters. The read and write permissions are defined based on the editor and commenters of the block and can be inherited from the database. Commenters are users who have permission to comment on the block. * **`comment`**: Represents a comment on a block. Each comment is associated with a block and has an author. The read and write permissions are defined based on the author of the comment and can be inherited from the block. * **`template`**: Represents a template within a workspace. Each template is associated with a workspace and has a creator and viewers. The read and write permissions are defined based on the creator and viewers of the template and can be inherited from the workspace. Permissions are also defined for creating and deleting templates. * **`integration`**: Represents an integration within a workspace. Each integration is associated with a workspace and has an owner. Permissions are defined for reading and writing to the integration. ### Permissions We have several actions attached with the entities, which are limited by certain permissions. Let's examine the **read** permission of the page entity. #### Page Read Permission ```perm theme={null} entity workspace { // The owner of the workspace relation owner @user // Members of the workspace relation member @user // Guests (users with read-only access) of the workspace relation guest @user // Bots associated with the workspace relation bot @user // Admin users who have permission to manage the workspace relation admin @user // Define permissions for workspace actions .. .. // Define permissions that can be inherited by child entities permission read = member or guest or bot or admin .. } entity page { // The workspace associated with the page relation workspace @workspace .. .. // The user(s) who can read the page (members of the workspace or guests) relation reader @user @workspace#member @workspace#guest .. .. // Define permissions for page actions permission read = reader or workspace.read .. .. } ``` This permission specifies who can read the contents of the page at Notion. The `reader` relation specifies the users who are members of the workspace associated with the page (`workspace#member`) or guests of the workspace (`workspace#guest`). Read permission of the workspace inherited as `workspace.read` in the page entity. THis permission specifies that any user who has been granted read access to the workspace object (i.e., the workspace that the page belongs to) can also read the page. In summary, any user who is a member or guest of the workspace and has been granted read access to the page through the reader relation, as well as any user who has been granted read access to the workspace itself, can read the contents of the page. ## Relationships Based on our schema, let's create some sample relationships to test both our schema and our authorization logic. ```perm theme={null} // Assign users to different workspaces: workspace:engineering_team#owner@user:alice workspace:engineering_team#member@user:bob workspace:engineering_team#guest@user:charlie workspace:engineering_team#admin@user:alice workspace:sales_team#owner@user:david workspace:sales_team#member@user:eve workspace:sales_team#guest@user:frank workspace:sales_team#admin@user:david // Connect pages, databases, and templates to workspaces: page:project_plan#workspace@workspace:engineering_team page:product_spec#workspace@workspace:engineering_team database:task_list#workspace@workspace:engineering_team template:weekly_report#workspace@workspace:sales_team database:customer_list#workspace@workspace:sales_team template:marketing_campaign#workspace@workspace:sales_team // Set permissions for pages, databases, and templates: page:project_plan#writer@user:frank page:project_plan#reader@user:bob database:task_list#editor@user:alice database:task_list#viewer@user:bob template:weekly_report#creator@user:alice template:weekly_report#viewer@user:bob page:product_spec#writer@user:david page:product_spec#reader@user:eve database:customer_list#editor@user:david database:customer_list#viewer@user:eve template:marketing_campaign#creator@user:david template:marketing_campaign#viewer@user:eve // Set relationships for blocks and comments: block:task_list_1#database@database:task_list block:task_list_1#editor@user:alice block:task_list_1#commenter@user:bob block:task_list_2#database@database:task_list block:task_list_2#editor@user:alice block:task_list_2#commenter@user:bob comment:task_list_1_comment_1#block@block:task_list_1 comment:task_list_1_comment_1#author@user:bob comment:task_list_1_comment_2#block@block:task_list_1 comment:task_list_1_comment_2#author@user:charlie comment:task_list_2_comment_1#block@block:task_list_2 comment:task_list_2_comment_1#author@user:bob comment:task_list_2_comment_2#block@block:task_list_2 comment:task_list_2_comment_2#author@user:charlie ``` ## Test & Validation Since we have our schema and the sample relation tuples, let's check some permissions and test our authorization logic. ```perm theme={null} entity database { // The workspace associated with the database relation workspace @workspace // The user who can edit the database relation editor @user .. .. // Define permissions for database actions .. .. permission write = editor or workspace.write .. .. } ``` According to what we have defined for the **'write'** permission, users who are either; * The editor in task list database (`database:task_list`) * Have a write permission in the engineering team workspace, which is the only workspace that task list is associated (`database:task_list#workspace@workspace:engineering_team`) can edit the task list database (`database:task_list`) Based on the relation tuples we created, `user:alice` doesn't have the **editor** relationship with the `database:task_list`. Since `user:alice` is the owner and admin in the engineering team workspace (`workspace:engineering_team#admin@user:alice`) it has a write permission defined in the workspace entity, as you can see below: ```perm theme={null} entity workspace { // The owner of the workspace relation owner @user .. .. // Admin users who have permission to manage the workspace relation admin @user .. .. // Define permissions that can be inherited by child entities .. permission write = owner or admin } ``` And as we mentioned the engineering team workspace is the only workspace that task list is associated (`database:task_list#workspace@workspace:engineering_team`). Therefore, the `user:alice write database:task_list` check request should yield a **'true'** response. ```perm theme={null} entity page { // The workspace associated with the page relation workspace @workspace // The user who can write to the page relation writer @user .. .. permission write = writer or workspace.write } ``` `user:charlie` is guest in the workspace (`workspace:engineering_team#guest@user:charlie`) and the engineering team workspace is the only workspace that `page:product_spec` belongs to. As we defined, guests doesn't have write permission in a workspace. ```perm theme={null} entity workspace { // The owner of the workspace relation owner @user // Admin users who have permission to manage the workspace relation admin @user .. .. permission write = owner or admin } ``` So that, `user:charlie` doesn't have a write relationship in the workspace. And ultimately, the `user:charlie write page:product_spec` check request should yield a **'false'** response. Let's test these access checks in our local with using **permify validator**. We'll use the below schema for the schema validation file. ```yaml theme={null} schema: >- entity user {} entity workspace { // The owner of the workspace relation owner @user // Members of the workspace relation member @user // Guests (users with read-only access) of the workspace relation guest @user // Bots associated with the workspace relation bot @user // Admin users who have permission to manage the workspace relation admin @user // Define permissions for workspace actions permission create_page = owner or member or admin permission invite_member = owner or admin permission view_workspace = owner or member or guest or bot permission manage_workspace = owner or admin // Define permissions that can be inherited by child entities permission read = member or guest or bot or admin permission write = owner or admin } entity page { // The workspace associated with the page relation workspace @workspace // The user who can write to the page relation writer @user // The user(s) who can read the page (members of the workspace or guests) relation reader @user @workspace#member @workspace#guest // Define permissions for page actions permission read = reader or workspace.read permission write = writer or workspace.write } entity database { // The workspace associated with the database relation workspace @workspace // The user who can edit the database relation editor @user // The user(s) who can view the database (members of the workspace or guests) relation viewer @user @workspace#member @workspace#guest // Define permissions for database actions permission read = viewer or workspace.read permission write = editor or workspace.write permission create = editor or workspace.write permission delete = editor or workspace.write } entity block { // The page associated with the block relation page @page // The database associated with the block relation database @database // The user who can edit the block relation editor @user // The user(s) who can comment on the block (readers of the parent object) relation commenter @user @page#reader // Define permissions for block actions permission read = database.read or commenter permission write = editor or database.write permission comment = commenter } entity comment { // The block associated with the comment relation block @block // The author of the comment relation author @user // Define permissions for comment actions permission read = block.read permission write = author } entity template { // The workspace associated with the template relation workspace @workspace // The user who creates the template relation creator @user // The user(s) who can view the page (members of the workspace or guests) relation viewer @user @workspace#member @workspace#guest // Define permissions for template actions permission read = viewer or workspace.read permission write = creator or workspace.write permission create = creator or workspace.write permission delete = creator or workspace.write } entity integration { // The workspace associated with the integration relation workspace @workspace // The owner of the integration relation owner @user // Define permissions for integration actions permission read = workspace.read permission write = owner or workspace.write } relationships: - workspace:engineering_team#owner@user:alice - workspace:engineering_team#member@user:bob - workspace:engineering_team#guest@user:charlie - workspace:engineering_team#admin@user:alice - workspace:sales_team#owner@user:david - workspace:sales_team#member@user:eve - workspace:sales_team#guest@user:frank - workspace:sales_team#admin@user:david - page:project_plan#workspace@workspace:engineering_team - page:product_spec#workspace@workspace:engineering_team - database:task_list#workspace@workspace:engineering_team - template:weekly_report#workspace@workspace:sales_team - database:customer_list#workspace@workspace:sales_team - template:marketing_campaign#workspace@workspace:sales_team - page:project_plan#writer@user:frank - page:project_plan#reader@user:bob - database:task_list#editor@user:alice - database:task_list#viewer@user:bob - template:weekly_report#creator@user:alice - template:weekly_report#viewer@user:bob - page:product_spec#writer@user:david - page:product_spec#reader@user:eve - database:customer_list#editor@user:david - database:customer_list#viewer@user:eve - template:marketing_campaign#creator@user:david - template:marketing_campaign#viewer@user:eve - block:task_list_1#database@database:task_list - block:task_list_1#editor@user:alice - block:task_list_1#commenter@user:bob - block:task_list_2#database@database:task_list - block:task_list_2#editor@user:alice - block:task_list_2#commenter@user:bob - comment:task_list_1_comment_1#block@block:task_list_1 - comment:task_list_1_comment_1#author@user:bob - comment:task_list_1_comment_2#block@block:task_list_1 - comment:task_list_1_comment_2#author@user:charlie - comment:task_list_2_comment_1#block@block:task_list_2 - comment:task_list_2_comment_1#author@user:bob - comment:task_list_2_comment_2#block@block:task_list_2 - comment:task_list_2_comment_2#author@user:charlie scenarios: - name: "scenario 1" description: "test description" checks: - entity: "database:task_list" subject: "user:alice" assertions: write: true - entity: "page:product_spec" subject: "user:charlie" assertions: write: false ``` ### Using Schema Validator in Local After cloning [Permify](https://github.com/Permify/permify), open up a new file and copy the **schema yaml file** content inside. Then, build and run Permify instance using the command `make serve`. ![Running Permify](https://user-images.githubusercontent.com/34595361/233155326-e1d2daf6-2406-4139-b0b3-5f7b54880593.png) Then run `permify validate {path of your schema validation file}` to start the test process. The validation result according to our example schema validation file: ![Screen Shot 2023-04-16 at 15 53 06](https://user-images.githubusercontent.com/34595361/233154924-c31a76f4-86f5-4ed3-a1ec-750b642927e6.png) ## Need any help? This is the end of the demonstration of the authorization structure for Notion. To install and implement this see the [Set Up Permify](../../installation.md) section. If you need any kind of help, our team is happy to help you get started with Permify. If you'd like to learn more about using Permify in your app or have any questions about it, [schedule a consultation call with one of our account executives](https://www.permify.co/book-demo).