Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

chore: rename configuration language to modeling language #686

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
18 changes: 9 additions & 9 deletions docs/content/concepts.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -151,10 +151,10 @@ Together with [relationship tuples](#what-is-a-relationship-tuple), the authoriz

<ProductName format={ProductNameFormat.LongForm}/> uses two different syntaxes to define the authorization model:

- A JSON syntax accepted by the <ProductName format={ProductNameFormat.ShortForm}/> 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 <ProductName format={ProductNameFormat.ShortForm}/> 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 <UpdateProductNameInLinks link="./configuration-language" name="{ProductName} Configuration Language" />.
Click here to learn more about the <UpdateProductNameInLinks link="./modeling-language" name="{ProductName} Modeling Language" />.

</details>

Expand Down Expand Up @@ -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.

</details>

Expand Down Expand Up @@ -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 <ProductName format={ProductNameFormat.ShortForm}/> 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 <ProductName format={ProductNameFormat.ShortForm}/> 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 <ProductName format={ProductNameFormat.ShortForm}/> authorization model allows it.

</summary>

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

- <RelationshipTuplesViewer
relationshipTuples={[
Expand Down Expand Up @@ -651,10 +651,10 @@ For more information, see [Modeling Public Access](./modeling/public-access.mdx)
id: './authorization-concepts',
},
{
title: 'Configuration Language',
description: 'Learning about the FGA configuration language',
link: './configuration-language',
id: './configuration-language',
title: 'Modeling Language',
description: 'Learning about the FGA modeling language',
Copy link
Member

@matthewpereira matthewpereira Mar 7, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In docs/content/getting-started/immutable-models.mdx we use {ProductName}, here and in some other cases we use FGA - which do you prefer?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think that Andres strongly prefers {ProductName} because it means the content can be recycled.

link: './modeling-language',
id: './modeling-language',
},
{
title: 'Direct access',
Expand Down
8 changes: 4 additions & 4 deletions docs/content/getting-started/immutable-models.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -61,10 +61,10 @@ const time = ulid.decodeTime(id);
description="Learn more about modeling and production usage in {ProductName}."
relatedLinks={[
{
title: 'Configuration Language',
description: 'Learn about the {ProductName} Configuration Language.',
link: '../configuration-language',
id: '../configuration-language',
title: 'Modeling Language',
description: 'Learn about the {ProductName} Modeling Language.',
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Elsewhere we seem to use sentence case, but here we use title case. I think sentence case is preferred, what do you think?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ideally we would pick one strategy and make it consistent everywhere, but let me know if I'm missing some nuance here.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Section titles are going to be sentence case, yes. My plan is to slightly modify our current style guide for FGA purposes.

link: '../modeling-language',
id: '../modeling-language',
},
{
title: 'Getting Started with Modeling',
Expand Down
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
---
title: Configuration Language
title: Modeling Language
sidebar_position: 2
slug: /configuration-language
description: Learning about the FGA configuration language and using it to build a representation of a system's authorization model
slug: /modeling-language
description: Learning about the FGA modeling language and using it to build a representation of a system's authorization model
---

import {
Expand All @@ -19,21 +19,21 @@ import {
WriteRequestViewer,
} from '@components/Docs';

# Configuration Language
# Modeling Language

<DocumentationNotice />

The <ProductName format={ProductNameFormat.LongForm}/>'s Configuration Language is used to build a representation of a system's _<ProductConcept section="what-is-an-authorization-model" linkName="authorization model" />_. It informs <UpdateProductNameInLinks link="/api/service" name="{ProductName}'s API" /> on what the <ProductConcept section="what-is-a-type" linkName="object types" /> in the system are and how they could relate to one another. It describes the <ProductConcept section="what-is-a-relation" linkName="relations" /> possible on an object of a certain type and lists the conditions under which one is related to that object.
The <ProductName format={ProductNameFormat.LongForm}/>'s Modeling Language is used to build a representation of a system's _<ProductConcept section="what-is-an-authorization-model" linkName="authorization model" />_. It informs <UpdateProductNameInLinks link="/api/service" name="{ProductName}'s API" /> on what the <ProductConcept section="what-is-a-type" linkName="object types" /> in the system are and how they could relate to one another. It describes the <ProductConcept section="what-is-a-relation" linkName="relations" /> 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 <ProductName format={ProductNameFormat.ShortForm}/>'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 <ProductName format={ProductNameFormat.ShortForm}/>'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 <ProductName format={ProductNameFormat.ShortForm}/> 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 <ProductConcept /> 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 <ProductName format={ProductNameFormat.ShortForm}/> configuration language.
Below is a sample authorization model. In the next sections we'll go over the building blocks that make the <ProductName format={ProductNameFormat.ShortForm}/> modeling language.

<AuthzModelSnippetViewer
configuration={{
Expand Down Expand Up @@ -299,7 +299,7 @@ For example, let's take a closer look at the `team` type.

This `team` _<ProductConcept section="what-is-a-type-definition" linkName="type definition" />_ defines all the _<ProductConcept section="what-is-a-relation" linkName="relations" />_ that _<ProductConcept section="what-is-a-user" linkName="users" />_ can have with an _<ProductConcept section="what-is-an-object" linkName="object" />_ 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 **<ProductConcept section="what-are-direct-and-implied-relationships" linkName="direct relationship" />** 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 **<ProductConcept section="what-are-direct-and-implied-relationships" linkName="direct relationship" />** with the `team` type as a `member` for objects of
- type `user`
- the `user` <ProductConcept section="what-is-type-bound-public-access" linkName="type bound public access" /> (`user:*`)
- [usersets](./modeling/building-blocks/usersets.mdx) that have a `team` type and a `member` relation (e.g. `team:product#member`)
Expand Down Expand Up @@ -1058,7 +1058,7 @@ Learn more about Zanzibar at the [Zanzibar Academy](https://zanzibar.academy).
## Related Sections

<RelatedSection
description="Check the following sections for more on how to use the configuration language in modeling authorization."
description="Check the following sections for more on how to use the modeling language in modeling authorization."
relatedLinks={[
{
title: '{ProductName} Concepts',
Expand Down
10 changes: 5 additions & 5 deletions docs/content/modeling/advanced/entitlements.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -57,10 +57,10 @@ You need to know how to disallow granting direct relation to an object and requi

Used here to indicate that "access" to a feature cannot be directly granted to a user, but is implied through the users organization subscribing to a plan that offers that feature.

#### Concepts & Configuration Language
#### Concepts & Modeling Language

- Some <ProductConcept />
- [Configuration Language](../../configuration-language.mdx)
- [Modeling Language](../../modeling-language.mdx)

</details>

Expand Down Expand Up @@ -354,7 +354,7 @@ Add it now. Like so:

In this tutorial, you will find the phrases <ProductConcept section="what-are-direct-and-implied-relationships" linkName="direct relationship and implied relationship" />.

A _direct relationship_ R between user X and object Y means the relationship tuple (user=X, relation=R, object=Y) exists, and the <ProductName format={ProductNameFormat.ShortForm}/> 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 <ProductName format={ProductNameFormat.ShortForm}/> 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 <ProductName format={ProductNameFormat.ShortForm}/> authorization model allows it.

Expand Down Expand Up @@ -905,8 +905,8 @@ In this tutorial, you learned:
- to model entitlements for a system in <ProductName format={ProductNameFormat.LongForm}/>
- how to start with a set of requirements and scenarios and iterate on the <ProductName format={ProductNameFormat.ShortForm}/> 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 <ProductName format={ProductNameFormat.ShortForm}/>
- 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 <ProductName format={ProductNameFormat.ShortForm}/> 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 <ProductName format={ProductNameFormat.ShortForm}/> authorization model, and how to block direct relationships by removing it

<Playground title="Entitlements" preset="entitlements" example="Entitlements" store="entitlements" />

Expand Down
6 changes: 3 additions & 3 deletions docs/content/modeling/advanced/gdrive.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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 <ProductConcept section="what-is-a-relation" linkName="relation" /> on an object imply another relation on the same object. See [Modeling Concepts: Concentric Relationships](../building-blocks/concentric-relationships.mdx) for more.<br />
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.<br />
- 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.<br />
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 **<ProductConcept section="what-is-type-bound-public-access" linkName="type bound public access" />** in a <ProductConcept section="what-is-a-relationship-tuple" linkName="relationship tuple's" /> user field to indicate that everyone has a certain relation with an object. See [Modeling Public Access](../public-access.mdx) for more.<br />
Used here to [share documents publicly](#04-sharing-files-and-folders-publicly).
Expand Down Expand Up @@ -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 <ProductConcept />
- [Configuration Language](../../configuration-language.mdx)
- [Modeling Language](../../modeling-language.mdx)

</details>

Expand Down
6 changes: 3 additions & 3 deletions docs/content/modeling/advanced/github.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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 <ProductConcept section="what-is-a-relation" linkName="relation" /> on an object imply another relation on the same object. See [Modeling Concepts: Concentric Relationships](../building-blocks/concentric-relationships.mdx) for more.<br />
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.<br />
- 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.<br />
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 <ProductName format={ProductNameFormat.ShortForm}/>.<br />
Used here to indicate that a repository admin on a GitHub organization, is an admin on all repositories that organization owns.
Expand Down Expand Up @@ -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 <ProductConcept />
- [Configuration Language](../../configuration-language.mdx)
- [Modeling Language](../../modeling-language.mdx)

</details>

Expand Down
Loading
Loading