docs: rewrite OPL as practical guide by DavudSafarli · Pull Request #2588 · ory/docs

DavudSafarli · 2026-05-26T06:15:02Z

This PR rewrites OPL into a practical how-to guide covering namespaces, relations, subject-set references, and permits, each section with examples

Copilot

Pull request overview

This PR rewrites the Ory Permission Language (OPL) reference page from a formal specification into a practical how-to guide, introducing core modeling concepts (namespaces, relations, subject-set references, and permits) via short examples.

Changes:

Replaced the EBNF/spec-style content with a step-by-step, example-driven guide.
Added focused examples for unions, SubjectSet<...> references, includes, traverse, boolean operators, and permission composition.
Consolidated into a single “complete example” schema showing direct, group-based, and inherited access patterns.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

+restricted: (ctx: Context) =>
+  this.related.allowlist.includes(ctx.subject) &&
+  !this.related.blocklist.includes(ctx.subject),
+```


+edit:  (ctx: Context) => this.related.owners.includes(ctx.subject),
+admin: (ctx: Context) => this.permits.edit(ctx) && this.related.admins.includes(ctx.subject),


zepatrik · 2026-05-28T15:28:56Z

+The `related` block defines who can be associated with an object. Each entry names a relation and declares what subject types it
+holds.


I think this can be confusing, as it is not necessarily clear what objects and subjects are here. I would either add something to namespaces section, or define object and subject here as the direction of relations.

Something along the lines:

Suggested change

The `related` block defines who can be associated with an object. Each entry names a relation and declares what subject types it

holds.

The `related` block defines the relations between namespaces (classes). Each relation has a direction: `subject` is in `relation` of `object`. The relations defined in an OPL class (object) declare the allowed subjects. Generally, relations should represent the "real-world" relations between objects and subjects.

Then add something after the example saying which relations this defines and what the objects/subjects are.

zepatrik · 2026-05-28T15:29:05Z

-identifier = letter { letter | digit } .
-digit      = "0" … "9" .
-letter     = "A" … "Z" | "a" … "z" | "_" .
+class File implements Namespace {


class User missing

zepatrik · 2026-05-28T15:30:58Z

-ClassDecl       = "class" identifier "implements" "Namespace" "{" ClassSpec "}" .
-ClassSpec       = [ RelationDecls ] | [ PermissionDefns] .
-```
+### Subject-set references


I propose to completely omit this section, as subject sets are not really useful currently. There is no specific reason to use them, right?

good point. Based on how we implement things, currently subjectsets are faster than traverse calls. In a place that traverse would cause 100 direct check calls, SubjectSet<> would make 1 call and get the answer.

But that's an implementation details, and technically, we can make optimizations to make them equally performant.

I think that's the only difference. Otherwise, Traverse is more future-proof as we can easily update/change the relationships form .members.includes(.) to .admin.includes(.).

Okay, see this answer: https://github.com/orgs/authzed/discussions/2851#discussioncomment-15608216

This is also one difference, though i don't think anyone would care about it.

I see, but the use-case is very narrow.
IMO the only relevant use-case is where the relation is dynamic, so the user can choose whether they want to grant permissions to all group members, only group admins, ... That requires the relation to not be in the OPL though, or allow narrowing it down to multiple relations. The use-case is not supported really rn.

zepatrik · 2026-05-28T15:31:43Z

 ```

-Note that all relations are defined as array types `T[]` because there are naturally only many-to-many relations in Keto.
+A subject can now be either a `User` directly, or any member of the `Group:engineering`.


Not clear to me what this means.

zepatrik · 2026-05-28T15:33:25Z


-```ts
-class User {}
+The `permits` block defines boolean functions the engine evaluates during a check.


Suggested change

The `permits` block defines boolean functions the engine evaluates during a check.

The `permits` block defines permissions. These are evaluated during a permission check request. Permissions are written as functions that return a boolean representing whether a permission is granted or not. While relations follow the real-world, permissions define application-specific rules based on relations.

zepatrik · 2026-05-28T15:44:11Z

-```
-
-The `ctx` object is a fixed parameter that contains the `subject` for which the permission check should be conducted:
+`this.related.x.traverse(g => ...)` iterates over the objects in relation `x` and evaluates the inner expression for each one.


Suggested change

`this.related.x.traverse(g => ...)` iterates over the objects in relation `x` and evaluates the inner expression for each one.

`this.related.x.traverse(g => ...)` iterates over the subjects in relation `x` and evaluates the inner expression for each one.

zepatrik · 2026-05-28T15:46:53Z

+edit:  (ctx: Context) => this.related.owners.includes(ctx.subject),
+admin: (ctx: Context) => this.permits.edit(ctx) && this.related.admins.includes(ctx.subject),


I think the example is not the most natural one

Suggested change

edit: (ctx: Context) => this.related.owners.includes(ctx.subject),

admin: (ctx: Context) => this.permits.edit(ctx) && this.related.admins.includes(ctx.subject),

isAdmin: (ctx: Context) => this.related.admins.includes(ctx.subject),

edit: (ctx: Context) => this.permits.isAdmin(ctx) ||this.related.owners.includes(ctx.subject),

zepatrik · 2026-05-28T15:50:43Z

  related: {
-    members: (User | Group)[]
+    members: (User | SubjectSet<Group, "members">)[]
  }


While the subject set works, I don't think it is the correct way of doing this. Having the parents explicitly here makes it a lot clearer and allows the relation to be reused in different permissions if one wants to add them (think admins of groups, ...)

Suggested change

related: {

members: (User | Group)[]

members: (User | SubjectSet<Group, "members">)[]

}

related: {

members: User[]

parents: Group[]

}

permits = {

isMember: (ctx: Context) => this.related.members.includes(ctx.subject) || this.related.parents.traverse((parent) => parent.permits.isMember(ctx))

I admit that it is not so nice in the other namespaces without the planned type assertions, but I think it is the better way of writing permissions.

zepatrik · 2026-05-28T15:55:43Z

+This schema models:
+
+- Direct access via `viewers` and `owners`
+- Group-based access via `SubjectSet<Group, "members">`
+- Inherited access from parent folders via `traverse`


Consider adding some of these details as comments, so it is more clear what you refer to. Consider adding more comments to the full example in general.

docs: rewrite OPL as practical guide

3cb1ffb

Copilot AI review requested due to automatic review settings May 26, 2026 06:15

DavudSafarli requested review from aeneasr, unatasha8 and vinckr as code owners May 26, 2026 06:15

Copilot started reviewing on behalf of DavudSafarli May 26, 2026 06:15 View session

github-actions Bot added the Needs Triage label May 26, 2026

ory-bot assigned DavudSafarli May 26, 2026

Copilot AI reviewed May 26, 2026

View reviewed changes

vercel Bot deployed to Preview May 26, 2026 06:19 View deployment

copilot reviews

877a314

vercel Bot deployed to Preview May 26, 2026 07:18 View deployment

github-actions Bot removed the Needs Triage label May 26, 2026

zepatrik requested changes May 28, 2026

View reviewed changes

		edit: (ctx: Context) => this.related.owners.includes(ctx.subject),
		admin: (ctx: Context) => this.permits.edit(ctx) && this.related.admins.includes(ctx.subject),

		The `related` block defines who can be associated with an object. Each entry names a relation and declares what subject types it
		holds.

	The `related` block defines who can be associated with an object. Each entry names a relation and declares what subject types it
	holds.
	The `related` block defines the relations between namespaces (classes). Each relation has a direction: `subject` is in `relation` of `object`. The relations defined in an OPL class (object) declare the allowed subjects. Generally, relations should represent the "real-world" relations between objects and subjects.

	The `permits` block defines boolean functions the engine evaluates during a check.
	The `permits` block defines permissions. These are evaluated during a permission check request. Permissions are written as functions that return a boolean representing whether a permission is granted or not. While relations follow the real-world, permissions define application-specific rules based on relations.

	`this.related.x.traverse(g => ...)` iterates over the objects in relation `x` and evaluates the inner expression for each one.
	`this.related.x.traverse(g => ...)` iterates over the subjects in relation `x` and evaluates the inner expression for each one.

Conversation

DavudSafarli commented May 26, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants