docs: rewrite OPL as practical guide#2588
Conversation
There was a problem hiding this comment.
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.
|
@zepatrik i replied to your comments. There are few things to resolve about subjectsets and final example. It's worth noting that reader ideally should read the other pages such as Namespaces/Objects/Subjects before jumping into OPL page. So, some understanding of the Namespace/Object/Subject should exist while reading this. This page is only for OPL reference. Not 1 page Keto guide. Though, the other pages also need improvement, and overall sidebar needs improvements. As a reader, i alway preferred 1 long page docs compared to small separate pages. |
zepatrik
left a comment
zepatrik
left a comment
There was a problem hiding this comment.
I'd say we're very close here. Probably the language needs a brush-up, but that can also be done by the docs people just rephrasing what is currently here.
unatasha8
left a comment
unatasha8
left a comment
There was a problem hiding this comment.
See my comments from Slack
zepatrik
left a comment
zepatrik
left a comment
There was a problem hiding this comment.
Lets merge this, we can still improve it later. It is good for now.
* docs: rewrite OPL as practical guide * copilot reviews * address review comments * make final example better * address review comments of una
This PR rewrites OPL into a practical how-to guide covering namespaces, relations, subject-set references, and permits, each section with examples