From 6c491165fd24f97b90de891ba21d99e2f3a4ea92 Mon Sep 17 00:00:00 2001 From: Raghd Hamzeh Date: Wed, 6 Mar 2024 19:05:55 -0500 Subject: [PATCH] chore: rename configuration language to modeling language --- docs/README.md | 2 +- docs/content/concepts.mdx | 18 ++++++------ .../getting-started/immutable-models.mdx | 8 +++--- ...ion-language.mdx => modeling-language.mdx} | 20 ++++++------- .../modeling/advanced/entitlements.mdx | 10 +++---- docs/content/modeling/advanced/gdrive.mdx | 6 ++-- docs/content/modeling/advanced/github.mdx | 6 ++-- docs/content/modeling/advanced/iot.mdx | 8 +++--- docs/content/modeling/advanced/slack.mdx | 8 +++--- docs/content/modeling/blocklists.mdx | 12 ++++---- .../building-blocks/direct-relationships.mdx | 4 +-- .../object-to-object-relationships.mdx | 2 +- .../modeling/building-blocks/usersets.mdx | 4 +-- docs/content/modeling/custom-roles.mdx | 4 +-- docs/content/modeling/direct-access.mdx | 8 +++--- docs/content/modeling/getting-started.mdx | 28 +++++++++---------- .../migrating/migrating-relations.mdx | 2 +- .../modeling/multiple-restrictions.mdx | 4 +-- .../organization-context-authorization.mdx | 2 +- docs/content/modeling/parent-child.mdx | 4 +-- docs/content/modeling/public-access.mdx | 8 +++--- .../modeling/roles-and-permissions.mdx | 6 ++-- docs/sidebars.js | 4 +-- docusaurus.config.js | 4 +++ 24 files changed, 93 insertions(+), 89 deletions(-) rename docs/content/{configuration-language.mdx => modeling-language.mdx} (96%) diff --git a/docs/README.md b/docs/README.md index e1d3a4c27..fe8eaa540 100644 --- a/docs/README.md +++ b/docs/README.md @@ -21,7 +21,7 @@ It offers an HTTP API, a gRPC API, and has SDKs for programming languages includ - [What is OpenFGA](./content/intro.mdx) - [Concepts](./content/concepts.mdx) -- [Configuration Language](./content/configuration-language.mdx) +- [Modeling Language](./content/modeling-language.mdx) - [Getting Started](./content/getting-started/overview.mdx) - [Setup OpenFGA](./content/getting-started/setup-openfga/overview.mdx) - [Configure OpenFGA](./content/getting-started/setup-openfga/configure-openfga.mdx) diff --git a/docs/content/concepts.mdx b/docs/content/concepts.mdx index 0edc42f64..822f361a6 100644 --- a/docs/content/concepts.mdx +++ b/docs/content/concepts.mdx @@ -151,10 +151,10 @@ Together with [relationship tuples](#what-is-a-relationship-tuple), the authoriz uses two different syntaxes to define the authorization model: -- A JSON syntax accepted by the API that closely follows the original syntax in the [Zanzibar Paper](https://research.google/pubs/pub48190/). For more information, see [Equivalent Zanzibar Concepts](./configuration-language.mdx#equivalent-zanzibar-concepts). +- A JSON syntax accepted by the API that closely follows the original syntax in the [Zanzibar Paper](https://research.google/pubs/pub48190/). For more information, see [Equivalent Zanzibar Concepts](./modeling-language.mdx#equivalent-zanzibar-concepts). - A simpler-to-use DSL that's accepted by both the [OpenFGA VS Code extension](https://marketplace.visualstudio.com/items?itemName=openfga.openfga-vscode) and [OpenFGA CLI](https://github.com/openfga/cli/) and offers syntax highlighting and validation in the VS Code extension. The DSL is used in the [Sample Stores](https://github.com/openfga/sample-stores) modeling examples and is translated to API-supported syntax using the CLI or [OpenFGA language](https://github.com/openfga/language) before being sent to the API. -Click here to learn more about the . +Click here to learn more about the . @@ -342,7 +342,7 @@ For the following model, only [relationship tuples](#what-is-a-relationship-tupl A relationship tuple with user `user:anne` or `user:3f7768e0-4fa7-4e93-8417-4da68ce1846c` may be written for objects with type `document` and relation `viewer`, so writing `{"user": "user:anne","relation":"viewer","object":"document:roadmap"}` succeeds. A relationship tuple with a disallowed user type for the `viewer` relation on objects of type `document` - for example `workspace:auth0` or `folder:planning#editor` - will be rejected, so writing `{"user": "folder:product","relation":"viewer","object":"document:roadmap"}` will fail. -This affects only relations that are [directly related](#what-are-direct-and-implied-relationships) and have [direct relationship type restrictions](./configuration-language.mdx#the-direct-relationship-type-restrictions) in their relation definition. +This affects only relations that are [directly related](#what-are-direct-and-implied-relationships) and have [direct relationship type restrictions](./modeling-language.mdx#the-direct-relationship-type-restrictions) in their relation definition. @@ -442,13 +442,13 @@ An [authorization model](#what-is-an-authorization-model), together with [relati ## What Are Direct And Implied Relationships? -A **direct relationship** (R) between user X and object Y means the relationship tuple (user=X, relation=R, object=Y) exists, and the authorization model for that relation allows the direct relationship because of [direct relationship type restrictions](./configuration-language.mdx#the-direct-relationship-type-restrictions)). +A **direct relationship** (R) between user X and object Y means the relationship tuple (user=X, relation=R, object=Y) exists, and the authorization model for that relation allows the direct relationship because of [direct relationship type restrictions](./modeling-language.mdx#the-direct-relationship-type-restrictions)). An **implied (or computed) relationship** (R) exists between user X and object Y if user X is related to an object Z that is in a direct or implied relationship with object Y, and the authorization model allows it. -- `user:anne` has a direct relationship with `document:new-roadmap` as `viewer` if the [type definition](#what-is-a-type-definition) allows it with [direct relationship type restrictions](./configuration-language.mdx#the-direct-relationship-type-restrictions), and one of the following [relationship tuples](#what-is-a-relationship-tuple) exist: +- `user:anne` has a direct relationship with `document:new-roadmap` as `viewer` if the [type definition](#what-is-a-type-definition) allows it with [direct relationship type restrictions](./modeling-language.mdx#the-direct-relationship-type-restrictions), and one of the following [relationship tuples](#what-is-a-relationship-tuple) exist: - -The 's Configuration Language is used to build a representation of a system's __. It informs on what the in the system are and how they could relate to one another. It describes the possible on an object of a certain type and lists the conditions under which one is related to that object. +The 's Modeling Language is used to build a representation of a system's __. It informs on what the in the system are and how they could relate to one another. It describes the possible on an object of a certain type and lists the conditions under which one is related to that object. -The **DSL** and the **JSON** syntax are two presentations of that configuration language. The JSON syntax is accepted by the API and closely matches the API described in the [Zanzibar paper](https://research.google/pubs/pub48190/). The DSL is syntactic sugar on top of the JSON syntax and compiles down to it before being sent to 's API. The DSL is meant to make modeling easier and more intuitive. +The **DSL** and the **JSON** syntax are two presentations of that modeling language. The JSON syntax is accepted by the API and closely matches the API described in the [Zanzibar paper](https://research.google/pubs/pub48190/). The DSL is syntactic sugar on top of the JSON syntax and compiles down to it before being sent to 's API. The DSL is meant to make modeling easier and more intuitive. You'll encounter the JSON syntax when calling the API directly or through the [SDKs](./getting-started), and the DSL when interacting with through the [Playground](https://play.fga.dev/). Throughout the documentation you can switch between the two presentations. To understand this guide better, you should be familiar with some and [How to get started on modeling](./modeling/getting-started.mdx). -## What Does The Configuration Language Look Like? +## What Does The Modeling Language Look Like? -Below is a sample authorization model. In the next sections we'll go over the building blocks that make the configuration language. +Below is a sample authorization model. In the next sections we'll go over the building blocks that make the modeling language. _ defines all the __ that __ can have with an __ of _type_ `team`. In this case the _relation_ is: `member`. -Due to the direct relationship type restrictions (`[user, team#member]`) being used, a user in the system can have a **** with the `team` type as a `member` for objects of +Due to the direct relationship type restrictions (`[user, team#member]`) being used, a user in the system can have a **** with the `team` type as a `member` for objects of - type `user` - the `user` (`user:*`) - [usersets](./modeling/building-blocks/usersets.mdx) that have a `team` type and a `member` relation (e.g. `team:product#member`) @@ -1058,7 +1058,7 @@ Learn more about Zanzibar at the [Zanzibar Academy](https://zanzibar.academy). ## Related Sections -- [Configuration Language](../../configuration-language.mdx) +- [Modeling Language](../../modeling-language.mdx) @@ -354,7 +354,7 @@ Add it now. Like so: In this tutorial, you will find the phrases . -A _direct relationship_ R between user X and object Y means the relationship tuple (user=X, relation=R, object=Y) exists, and the authorization model for that relation allows this direct relationship (by use of [direct relationship type restrictions](../../configuration-language.mdx#the-direct-relationship-type-restrictions)). +A _direct relationship_ R between user X and object Y means the relationship tuple (user=X, relation=R, object=Y) exists, and the authorization model for that relation allows this direct relationship (by use of [direct relationship type restrictions](../../modeling-language.mdx#the-direct-relationship-type-restrictions)). An _implied relationship_ R exists between user X and object Y if user X is related to an object Z that is in direct or implied relationship with object Y, and the authorization model allows it. @@ -905,8 +905,8 @@ In this tutorial, you learned: - to model entitlements for a system in - how to start with a set of requirements and scenarios and iterate on the authorization model until the checks match the expected scenarios - how to model [**parent-child relationships**](../parent-child.mdx) to indicate that a user having a relationship with a certain object implies having a relationship with another object in -- how to use [**the union operator**](../../configuration-language.mdx#the-union-operator) condition to indicate multiple possible paths for a relationship between two objects to be computed -- using [**direct relationship type restrictions**](../../configuration-language.mdx#the-direct-relationship-type-restrictions) in a authorization model, and how to block direct relationships by removing it +- how to use [**the union operator**](../../modeling-language.mdx#the-union-operator) condition to indicate multiple possible paths for a relationship between two objects to be computed +- using [**direct relationship type restrictions**](../../modeling-language.mdx#the-direct-relationship-type-restrictions) in a authorization model, and how to block direct relationships by removing it diff --git a/docs/content/modeling/advanced/gdrive.mdx b/docs/content/modeling/advanced/gdrive.mdx index 3fc6cc60a..7fb9198ac 100644 --- a/docs/content/modeling/advanced/gdrive.mdx +++ b/docs/content/modeling/advanced/gdrive.mdx @@ -30,7 +30,7 @@ This tutorial explains how to represent [Google Drive](https://www.google.com/in Used here to indicate that all users within a domain can access a document (sharing a document within an organization). - Model **concentric relationship** to have a certain on an object imply another relation on the same object. See [Modeling Concepts: Concentric Relationships](../building-blocks/concentric-relationships.mdx) for more.
Used here is to indicate that writers are also commenters and viewers. -- Using [**the union operator**](../../configuration-language.mdx#the-union-operator) condition to indicate that a user might have a certain relation with an object if they match any of the criteria indicated.
+- Using [**the union operator**](../../modeling-language.mdx#the-union-operator) condition to indicate that a user might have a certain relation with an object if they match any of the criteria indicated.
Used here to indicate that a user can be a viewer on a document, or can have the viewer relationship implied through commenter. - Using the **** in a user field to indicate that everyone has a certain relation with an object. See [Modeling Public Access](../public-access.mdx) for more.
Used here to [share documents publicly](#04-sharing-files-and-folders-publicly). @@ -68,10 +68,10 @@ Used here to indicate that users who have access to view a folder have access to You need to know how to add a relationship tuple to indicate that a resource is publicly available. [Learn more →](../public-access.mdx) -#### Concepts & Configuration Language +#### Concepts & Modeling Language - The -- [Configuration Language](../../configuration-language.mdx) +- [Modeling Language](../../modeling-language.mdx) diff --git a/docs/content/modeling/advanced/github.mdx b/docs/content/modeling/advanced/github.mdx index 60081bd6c..98a4785f5 100644 --- a/docs/content/modeling/advanced/github.mdx +++ b/docs/content/modeling/advanced/github.mdx @@ -29,7 +29,7 @@ This tutorial explains how to model GitHub's Organization permission model using Used here to indicate that all members of an organization are repository admins on the organization. - Modeling **concentric relationship** to have a certain on an object imply another relation on the same object. See [Modeling Concepts: Concentric Relationships](../building-blocks/concentric-relationships.mdx) for more.
Used here to indicate that maintainers of a repository are also writers of that repository. -- Using [**the union operator**](../../configuration-language.mdx#the-union-operator) condition to indicate that a user might have a certain relation with an object if they match any of the criteria indicated.
+- Using [**the union operator**](../../modeling-language.mdx#the-union-operator) condition to indicate that a user might have a certain relation with an object if they match any of the criteria indicated.
Used here to indicate that a user can be a reader on a repository, or can have the reader relationship implied through triager. - Model [**parent-child objects**](../parent-child.mdx) to indicate that a user having a relationship with a certain object implies having a relationship with another object in .
Used here to indicate that a repository admin on a GitHub organization, is an admin on all repositories that organization owns. @@ -61,10 +61,10 @@ You need to know how to create relationships between objects and how that might Used here to indicate that users who have repo admin access on an organization, have admin access to all repositories owned by that organization. -#### Concepts & Configuration Language +#### Concepts & Modeling Language - Some -- [Configuration Language](../../configuration-language.mdx) +- [Modeling Language](../../modeling-language.mdx) diff --git a/docs/content/modeling/advanced/iot.mdx b/docs/content/modeling/advanced/iot.mdx index 63d991cfc..b719c38ff 100644 --- a/docs/content/modeling/advanced/iot.mdx +++ b/docs/content/modeling/advanced/iot.mdx @@ -66,10 +66,10 @@ You need to know how to add users to groups and create relationships between gro Used here to indicate that security guards on a certain group are security guards on a device in that group. -#### Concepts & Configuration Language +#### Concepts & Modeling Language - Some -- [Configuration Language](../../configuration-language.mdx) +- [Modeling Language](../../modeling-language.mdx) @@ -717,7 +717,7 @@ To remedy this, remove `[user]` from `live_video_viewer`, `recorded_video_viewer :::info -Notice that any reference to the [**direct relationship type restrictions**](../../configuration-language.mdx#the-direct-relationship-type-restrictions) has been removed. That indicates that a user cannot have a with an object in this type. +Notice that any reference to the [**direct relationship type restrictions**](../../modeling-language.mdx#the-direct-relationship-type-restrictions) has been removed. That indicates that a user cannot have a with an object in this type. With this change, `anne` can no longer have a `live_video_viewer` permission for `device:1` except through having a `security_guard` or `it_admin` role first, and when she loses access to that role, she will automatically lose access to the `live_video_viewer` permission. @@ -749,7 +749,7 @@ To test this, we can add a new user `emily`. Emily is **not** a `security_guard` ]} /> -Now try to query `is emily related to device:1 as live_video_viewer?`. The returned result should be `emily is not related to device:1 as live_video_viewer`. This confirms that direct relations have no effect on the `live_video_viewer` relations, and that is because the [**direct relationship type restriction**](../../configuration-language.mdx#the-direct-relationship-type-restrictions) was removed from the relation configuration. +Now try to query `is emily related to device:1 as live_video_viewer?`. The returned result should be `emily is not related to device:1 as live_video_viewer`. This confirms that direct relations have no effect on the `live_video_viewer` relations, and that is because the [**direct relationship type restriction**](../../modeling-language.mdx#the-direct-relationship-type-restrictions) was removed from the relation configuration. diff --git a/docs/content/modeling/advanced/slack.mdx b/docs/content/modeling/advanced/slack.mdx index 595193160..ee809d577 100644 --- a/docs/content/modeling/advanced/slack.mdx +++ b/docs/content/modeling/advanced/slack.mdx @@ -32,7 +32,7 @@ This tutorial explains how to model permissions for a communication platform lik - How to Model **concentric relationship** to have a certain on an object imply another relation on the same object.
Used here to indicate that legacy admins have all the permissions of the more granular channels admin.
See [Modeling Concentric Relationships](../building-blocks/concentric-relationships.mdx) for more. -- How to use [**the union operator**](../../configuration-language.mdx#the-union-operator) condition to indicate that a user might have a certain relation with an object if they match any of the criteria indicated. +- How to use [**the union operator**](../../modeling-language.mdx#the-union-operator) condition to indicate that a user might have a certain relation with an object if they match any of the criteria indicated. @@ -59,10 +59,10 @@ You need to know how to create an authorization model and create a relationship You need to know how to update the authorization model to allow having nested relations such as all writers are readers. [Learn more →](../building-blocks/concentric-relationships.mdx) -#### Concepts & Configuration Language +#### Concepts & Modeling Language - Some -- [Configuration Language](../../configuration-language.mdx) +- [Modeling Language](../../modeling-language.mdx) @@ -201,7 +201,7 @@ Here is how you would express than in with an object of the type the relation specifies. +[Direct relationship type restrictions](../../modeling-language.mdx#the-direct-relationship-type-restrictions) indicate that a user can have a with an object of the type the relation specifies. ::: diff --git a/docs/content/modeling/blocklists.mdx b/docs/content/modeling/blocklists.mdx index 1f3144562..6f4aa0e3d 100644 --- a/docs/content/modeling/blocklists.mdx +++ b/docs/content/modeling/blocklists.mdx @@ -125,7 +125,7 @@ You need to know how to add users to groups and grant groups access to resources - A : is a string defined in the type definition of an authorization model that defines the possibility of a relationship between an object of the same type as the type definition and a user in the system - An : represents an entity in the system. Users' relationships to it can be define through relationship tuples and the authorization model - A : a grouping consisting of a user, a relation and an object stored in -- [Exclusion Operator](../configuration-language.mdx#the-exclusion-operator): the exclusion operator can be used to exclude certain usersets from being related to an object +- [Exclusion Operator](../modeling-language.mdx#the-exclusion-operator): the exclusion operator can be used to exclude certain usersets from being related to an object @@ -206,7 +206,7 @@ Now we can add relationship tuples indicating that a certain user is `blocked` f ### 02. Modify Our Model So Users Who Are Blocked Can No Longer Edit The Document -Now that we can mark users as `blocked` from editing documents, we need to support denying the `editor` relationship when a user is `blocked`. We do that by modifying the relation definition of `editor`, and making use of the [**the exclusion operator**](../configuration-language.mdx#the-exclusion-operator) to exclude the set of `blocked` users, as we can see here: +Now that we can mark users as `blocked` from editing documents, we need to support denying the `editor` relationship when a user is `blocked`. We do that by modifying the relation definition of `editor`, and making use of the [**the exclusion operator**](../modeling-language.mdx#the-exclusion-operator) to exclude the set of `blocked` users, as we can see here: : is a string defined in the type definition of an authorization model that defines the possibility of a relationship between an object of the same type as the type definition and a user in the system - An : represents an entity in the system. Users' relationships to it can be define through relationship tuples and the authorization model - A : a grouping consisting of a user, a relation and an object stored in -- [Direct Relationship Type Restrictions](../../configuration-language.mdx#the-direct-relationship-type-restrictions): used in the context of the relation definition can be used to allow direct relationships to the objects of this type +- [Direct Relationship Type Restrictions](../../modeling-language.mdx#the-direct-relationship-type-restrictions): used in the context of the relation definition can be used to allow direct relationships to the objects of this type @@ -79,7 +79,7 @@ When checking for a relationship, a direct relationship exists if a __ by adding [direct relationship type restrictions](../../configuration-language.mdx#the-direct-relationship-type-restrictions) from that . Likewise, they can be disabled by removing the direct relationship type restrictions. +Direct relationships can be enabled for a specific relation on an __ by adding [direct relationship type restrictions](../../modeling-language.mdx#the-direct-relationship-type-restrictions) from that . Likewise, they can be disabled by removing the direct relationship type restrictions. via [direct relationship type restrictions](../../configuration-language.mdx#the-direct-relationship-type-restrictions). +- via [direct relationship type restrictions](../../modeling-language.mdx#the-direct-relationship-type-restrictions). or `this` - object to object relationship where a user can access because it is a subscriber_member of a particular plan AND that plan is associated with the feature. diff --git a/docs/content/modeling/building-blocks/usersets.mdx b/docs/content/modeling/building-blocks/usersets.mdx index 4b992e3f0..50d4ef676 100644 --- a/docs/content/modeling/building-blocks/usersets.mdx +++ b/docs/content/modeling/building-blocks/usersets.mdx @@ -170,14 +170,14 @@ If we wanted to see which users and usersets have a `reader` relationship with ` } ``` -As you can see from the response above, with usersets we can express [unions](../../configuration-language.mdx#the-union-operator) of user groups. We can also express [intersections](../../configuration-language.mdx#the-intersection-operator) and [exclusions](../../configuration-language.mdx#the-exclusion-operator). +As you can see from the response above, with usersets we can express [unions](../../modeling-language.mdx#the-union-operator) of user groups. We can also express [intersections](../../modeling-language.mdx#the-intersection-operator) and [exclusions](../../modeling-language.mdx#the-exclusion-operator). ## Internals Using the type definitions in the authorization model, some of the situations we can represent are: - that a user is **not** in a set of users having a certain relation to an object, even if a relationship tuple exists in the system. See [Disabling Direct Relationships](./direct-relationships.mdx#2-with-direct-relationships-disabled) -- that a user has a certain relationship with an object if they are in the [union](../../configuration-language.mdx#the-union-operator), [intersection](../../configuration-language.mdx#the-intersection-operator) or [exclusion](../../configuration-language.mdx#the-exclusion-operator) of usersets. +- that a user has a certain relationship with an object if they are in the [union](../../modeling-language.mdx#the-union-operator), [intersection](../../modeling-language.mdx#the-intersection-operator) or [exclusion](../../modeling-language.mdx#the-exclusion-operator) of usersets. - that a user being in a set of users having a certain relation to an object can result in them having another relation to the object. See [Concentric Relationships](./concentric-relationships.mdx) - that the user being in a set of users having a certain relation to an object and that object is in a set of users having a certain relation to another object, can imply that the original user has a certain relationship to the final object. See [Object-to-Object Relationships](./object-to-object-relationships.mdx) diff --git a/docs/content/modeling/custom-roles.mdx b/docs/content/modeling/custom-roles.mdx index a2f02aaa4..36fb000c9 100644 --- a/docs/content/modeling/custom-roles.mdx +++ b/docs/content/modeling/custom-roles.mdx @@ -104,10 +104,10 @@ You need to know how to add users to groups and grant groups access to resources You need to know how to create relationships between objects and how that might affect a user's relationships to those objects. [Learn more →](./building-blocks/object-to-object-relationships.mdx) -### Concepts & Configuration Language +### Concepts & Modeling Language - -- [Configuration Language](../configuration-language.mdx) +- [Modeling Language](../modeling-language.mdx) diff --git a/docs/content/modeling/direct-access.mdx b/docs/content/modeling/direct-access.mdx index 7de265dac..b145f89f0 100644 --- a/docs/content/modeling/direct-access.mdx +++ b/docs/content/modeling/direct-access.mdx @@ -139,10 +139,10 @@ If we were to _check_ the following: **"is bob a viewer of document:meeting_note id: './getting-started', }, { - title: 'Configuration Language', - description: 'Learn about {ProductName} Configuration Language.', - link: '../configuration-language', - id: '../configuration-language', + title: 'Modeling Language', + description: 'Learn about {ProductName} Modeling Language.', + link: '../modeling-language', + id: '../modeling-language', }, ]} /> diff --git a/docs/content/modeling/getting-started.mdx b/docs/content/modeling/getting-started.mdx index d58618add..5a55d438a 100644 --- a/docs/content/modeling/getting-started.mdx +++ b/docs/content/modeling/getting-started.mdx @@ -328,7 +328,7 @@ We will also need to add "User" to the list as it establishes the type of user w , alignment: 'left', label: 'Drive' }} /> -Now that we have a list of object types we can start defining them using the : +Now that we have a list of object types we can start defining them using the : , relations can only have alphanumeric characters, underscores and hyphens. We recommend using underscore (\_) to separate words and removing prepositions. E.g.: "can create a document" can become "can_create_document" or "create_document" if you are into brevity. ::: -Using the we can enumerate the relations for each type: +Using the we can enumerate the relations for each type: ```dsl.openfga model @@ -521,7 +521,7 @@ You're now in the process of building a version you can use. The model above is ![Define relations](./assets/getting-started-diagram-05.svg) -We will use the to create a for each of the relations we identified. At this stage we will encode the answers to the question we asked at the beginning of the document:. +We will use the to create a for each of the relations we identified. At this stage we will encode the answers to the question we asked at the beginning of the document:.
accepts in the "user" parameter to write [object to object relationships](./building-blocks/object-to-object-relationships.mdx). You can read more about writing data to manage object to object relationships in [Managing Relationships Between Objects](../interacting/managing-relationships-between-objects.mdx). @@ -808,7 +808,7 @@ We need to express the following in the : +We can achieve that with the following definition using : : +Similar to the [can_share relation](#relation-can_share), we can achieve that with the following definition using : : +Similar to the [can_share relation](#relation-can_share), we can achieve that with the following definition using : : +Similar to the [can_share relation](#relation-can_share), we can achieve that with the following definition using : : is a string defined in the type definition of an authorization model that defines the possibility of a relationship between an object of the same type as the type definition and a user in the system - An : represents an entity in the system. Users' relationships to it can be define through relationship tuples and the authorization model - A : a grouping consisting of a user, a relation and an object stored in -- [Intersection Operator](../../configuration-language.mdx#the-intersection-operator): the intersection operator can be used to indicate a relationship exists if the user is in all the sets of users +- [Intersection Operator](../../modeling-language.mdx#the-intersection-operator): the intersection operator can be used to indicate a relationship exists if the user is in all the sets of users ## Step By Step diff --git a/docs/content/modeling/multiple-restrictions.mdx b/docs/content/modeling/multiple-restrictions.mdx index 6fa9b536f..7a0c1e1e3 100644 --- a/docs/content/modeling/multiple-restrictions.mdx +++ b/docs/content/modeling/multiple-restrictions.mdx @@ -165,7 +165,7 @@ You need to know how to model roles for users at the object level and model perm - A : is a string defined in the type definition of an authorization model that defines the possibility of a relationship between an object of the same type as the type definition and a user in the system - An : represents an entity in the system. Users' relationships to it can be define through relationship tuples and the authorization model - A : a grouping consisting of a user, a relation and an object stored in -- [Intersection Operator](../configuration-language.mdx#the-intersection-operator): the intersection operator can be used to indicate a relationship exists if the user is in all the sets of users +- [Intersection Operator](../modeling-language.mdx#the-intersection-operator): the intersection operator can be used to indicate a relationship exists if the user is in all the sets of users @@ -188,7 +188,7 @@ To do this, we need to: ### 01. Add can_delete Relation To Only Allow Writers That Are Members Of The Ownership Organization -The first step is to add the relation definition for `can_delete` so that it requires users to be both `writer` and `member` of the owner. This is accomplished via the keyword [`and`](../configuration-language.mdx#the-intersection-operator). +The first step is to add the relation definition for `can_delete` so that it requires users to be both `writer` and `member` of the owner. This is accomplished via the keyword [`and`](../modeling-language.mdx#the-intersection-operator). configuration language's support for [intersection](../configuration-language.mdx#the-intersection-operator) to specify that a user has to both have access _and_ be in the correct context in order to be authorized. +In order to add a restriction based on the current organization context, we will make use of modeling language's support for [intersection](../modeling-language.mdx#the-intersection-operator) to specify that a user has to both have access _and_ be in the correct context in order to be authorized. We can do that by introducing some new relations and updating existing relation definitions: diff --git a/docs/content/modeling/parent-child.mdx b/docs/content/modeling/parent-child.mdx index b14870ab5..13fb6c1e1 100644 --- a/docs/content/modeling/parent-child.mdx +++ b/docs/content/modeling/parent-child.mdx @@ -102,7 +102,7 @@ You need to know how to create an authorization model and create a relationship - A : is a string defined in the type definition of an authorization model that defines the possibility of a relationship between an object of the same type as the type definition and a user in the system - An : represents an entity in the system. Users' relationships to it can be define through relationship tuples and the authorization model - A : a grouping consisting of a user, a relation and an object stored in -- [Union Operator](../configuration-language.mdx#the-union-operator): the union operator can be used to indicate that the user has multiple ways of being related to an object +- [Union Operator](../modeling-language.mdx#the-union-operator): the union operator can be used to indicate that the user has multiple ways of being related to an object @@ -298,7 +298,7 @@ The chain of resolution becomes: :::caution Note that when searching tuples that are related to the object (the word after `from`, also called the tupleset), will not do any evaluation and will only consider concrete objects (of the form `:`) that were directly assigned, and will throw an error if it encounters any rewrites, or a `*`, a type bound public access (`:*`) or a userset (`:#`). -See [Referencing Relations on Related Objects](../configuration-language.mdx#referencing-relations-on-related-objects) for more. +See [Referencing Relations on Related Objects](../modeling-language.mdx#referencing-relations-on-related-objects) for more. ::: ## Related Sections diff --git a/docs/content/modeling/public-access.mdx b/docs/content/modeling/public-access.mdx index 9aff3ecdf..352c58c97 100644 --- a/docs/content/modeling/public-access.mdx +++ b/docs/content/modeling/public-access.mdx @@ -175,10 +175,10 @@ Once the above _relationship tuple_ is added, we can : represents an entity in the system. Users' relationships to it can be define through relationship tuples and the authorization model - A : a grouping consisting of a user, a relation and an object stored in Auth - A : will be called to check if there is a relationship between a user and an object, indicating that the access is allowed -- [Direct Relationship Type Restrictions](../configuration-language.mdx#the-direct-relationship-type-restrictions): can be used to indicate direct relationships between users and objects +- [Direct Relationship Type Restrictions](../modeling-language.mdx#the-direct-relationship-type-restrictions): can be used to indicate direct relationships between users and objects - A the Check API Request is used to check for relationships between users and objects @@ -158,7 +158,7 @@ Relating roles within can be ### 02. Adding Permissions For Bookings -Permissions within can be best described as the following: **Permissions are relations that users get only through other relations.** To represent permissions, we avoid adding a [**direct relationship type restriction**](../configuration-language.mdx#the-direct-relationship-type-restrictions) to the relation in the authorization model. Instead, we define the relation from other relations to indicate that it is a permission granted to and implied from a different relation. +Permissions within can be best described as the following: **Permissions are relations that users get only through other relations.** To represent permissions, we avoid adding a [**direct relationship type restriction**](../modeling-language.mdx#the-direct-relationship-type-restrictions) to the relation in the authorization model. Instead, we define the relation from other relations to indicate that it is a permission granted to and implied from a different relation. To add permissions related to bookings, we can add new relations to the `trip` _object_ type denoting the various actions a user can take on `trips` (view, edit, delete, rename, etc...) @@ -219,7 +219,7 @@ To allow `viewers` of a `trip` to have **permissions to view bookings** and `own }} /> -> Note: notice how both `booking_viewer` and `booking_adder` don't have [direct relationship type restrictions](../configuration-language.mdx#the-direct-relationship-type-restrictions). This is to ensure that the relation can only be assigned through the **role** and not directly. +> Note: notice how both `booking_viewer` and `booking_adder` don't have [direct relationship type restrictions](../modeling-language.mdx#the-direct-relationship-type-restrictions). This is to ensure that the relation can only be assigned through the **role** and not directly. ### 03. Checking User Roles And Their Permissions diff --git a/docs/sidebars.js b/docs/sidebars.js index 86a459905..1485ca6b3 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -18,8 +18,8 @@ const sidebars = { }, { type: 'doc', - label: 'Configuration Language', - id: 'content/configuration-language', + label: 'Modeling Language', + id: 'content/modeling-language', }, { type: 'category', diff --git a/docusaurus.config.js b/docusaurus.config.js index e83b10cd4..6aa2ccc14 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -164,6 +164,10 @@ import dev.openfga.sdk.api.configuration.ClientConfiguration;`, { to: '/docs/fga', from: '/docs', + }, + { + to: '/docs/modeling-language', + from: '/docs/configuration-language', } ], }),