docs: define authorization schema discovery by mariajgrimaldi · Pull Request #423 · openedx/openedx-authz

mariajgrimaldi · 2026-08-27T19:06:55Z

Description

Applications need a standard way to ship authz schema files with their code, and deployment must find the same definitions in Tutor, native deployments, and local development. Hardcoded filesystem paths would make discovery depend on a particular installation layout.

This ADR uses a Python entry point and package resources to discover schemas during deployment. It also records portable source information for each contribution and defines how the deployment command handles schemas from applications that have been removed.

Merge checklist:
Check off if complete or not applicable:

Version bumped
Changelog record added
Documentation updated (not only docstrings)
Fixup commits are squashed away
Unit tests added/updated
Manual testing instructions provided
Noted any: Concerns, dependencies, migration issues, deadlines, tickets

openedx-webhooks · 2026-08-27T19:07:00Z

Thanks for the pull request, @mariajgrimaldi!

This repository is currently maintained by @openedx/committers-openedx-authz.

Once you've gone through the following steps feel free to tag them in a comment and let them know that your changes are ready for engineering review.

🔘 Get product approval

If you haven't already, check this list to see if your contribution needs to go through the product review process.

If it does, you'll need to submit a product proposal for your contribution, and have it reviewed by the Product Working Group.
- This process (including the steps you'll need to take) is documented here.
If it doesn't, simply proceed with the next step.

🔘 Provide context

To help your reviewers and other members of the community understand the purpose and larger context of your changes, feel free to add as much of the following information to the PR description as you can:

Dependencies

This PR must be merged before / after / at the same time as ...
Blockers

This PR is waiting for OEP-1234 to be accepted.
Timeline information

This PR must be merged by XX date because ...
Partner information

This is for a course on edx.org.
Supporting documentation
Relevant Open edX discussion forum threads

🔘 Get a green build

If one or more checks are failing, continue working on your changes until this is no longer the case and your build turns green.

Details

Where can I find more information?

If you'd like to get more details on all aspects of the review process for open source pull requests (OSPRs), check out the following resources:

When can I expect my changes to be merged?

Our goal is to get community contributions seen and reviewed as efficiently as possible.

However, the amount of time that it takes to review and merge a PR can vary significantly based on factors such as:

The size and impact of the changes that it introduces
The need for product review
Maintenance status of the parent repository

💡 As a result it may take up to several weeks or months to complete a review and merge your PR.

rodmgwgu

Looking good, just a couple of points to discuss.

rodmgwgu · 2026-08-31T21:24:16Z

+
+* An application can ship authorization definitions with its code.
+* Tutor and other deployment systems use the same mechanism to discover and load the definitions.
+* Source information remains consistent across container.


nit: "containers" instead of "container"

rodmgwgu · 2026-08-31T21:27:49Z

+#. Removed applications
+=======================
+
+When an application is disabled or removed, the next deployment removes the static definitions that came only from that application. If users are assigned to one of its roles, deployment stops and reports those assignments so that an operator can remove them or move the users to another role. Shared definitions remain available when another application still provides them.


One thing I think we need to define:

What happens if, for example, we add "app-b" and "app-c" to a site, where app-c extends app-b roles. But then at a later time, app-b get's removed. What happens with this dependency?

My first thought is that this should also stop the deployment and error out a missing dependency.

Thanks for raising this!

Yes! I also think we should offer these alternatives: 1. error by default 2. allow for removal only if configured (as we defined for role_extensions in a previous ADR)

BryanttV

Thanks! I just want to clarify a few things

BryanttV · 2026-08-31T20:13:48Z

+
+An application contributes one or more authz schema resources through a Python entry point defined by ``openedx-authz``. Discovery resolves those resources with ``importlib.resources`` and returns all contributions in a defined order, since Python package discovery order may vary.
+
+For example, a ``course_authoring`` package can register ``course_authoring.authz:get_schema_resources`` and return ``authz/course_roles.authz.yaml`` and ``authz/course_permissions.authz.yaml``.


This example makes me wonder. Is a single file proposed that contains both roles/role extensions and permissions/permission categories? Or would they be two separate files? Or would both options be valid?

I don't think it should matter, the authz library should load all the registered resources and apply the extensions. I could change this so the example points to a single file and we can work retroactively in the reference folder to include real examples of how this would look.

I changed it! I'll also add a short code example to illustrate

BryanttV · 2026-08-31T21:33:13Z

+#. Python entry point and package resources
+===========================================
+
+An application contributes one or more authz schema resources through a Python entry point defined by ``openedx-authz``. Discovery resolves those resources with ``importlib.resources`` and returns all contributions in a defined order, since Python package discovery order may vary.


Should we define the entry point name right away? I'm thinking of authz.schema or something similar 🤔

Yes! I added it!

That would make sense! I'll add the decision to this section

BryanttV · 2026-08-31T21:35:13Z

+
+An application contributes one or more authz schema resources through a Python entry point defined by ``openedx-authz``. Discovery resolves those resources with ``importlib.resources`` and returns all contributions in a defined order, since Python package discovery order may vary.
+
+For example, a ``course_authoring`` package can register ``course_authoring.authz:get_schema_resources`` and return ``authz/course_roles.authz.yaml`` and ``authz/course_permissions.authz.yaml``.


What should happen if, for example, the get_schema_resources function throws an exception? Does the discovery stop, or is it reported as an isolated failure of that app and it continues with the rest?

Thank you for raising this! Since we're doing this during runtime, I think for correctness and auditability of the schema maybe we should fail and maybe allow for a different behavior?

openedx-webhooks added open-source-contribution PR author is not from Axim or 2U core contributor PR author is a Core Contributor (who may or may not have write access to this repo). labels Aug 27, 2026

openedx-webhooks added this to Contributions Aug 27, 2026

github-project-automation Bot moved this to Needs Triage in Contributions Aug 27, 2026

mariajgrimaldi linked an issue Aug 27, 2026 that may be closed by this pull request

Role and permission definition ADR #409

Open

mphilbrick211 moved this from Needs Triage to Waiting on Author in Contributions Aug 27, 2026

rodmgwgu reviewed Aug 31, 2026

View reviewed changes

BryanttV reviewed Aug 31, 2026

View reviewed changes

mariajgrimaldi force-pushed the MJG/authz-schema/discovery branch from b75eb99 to 5d42335 Compare September 1, 2026 16:03

mariajgrimaldi force-pushed the MJG/authz-schema/discovery branch from 5d42335 to 5483288 Compare September 1, 2026 16:12

mariajgrimaldi force-pushed the MJG/authz-schema/discovery branch from 5483288 to 11b6b03 Compare September 1, 2026 16:21

mariajgrimaldi force-pushed the MJG/authz-schema/discovery branch from 11b6b03 to 8454483 Compare September 1, 2026 16:27

mariajgrimaldi added 2 commits September 1, 2026 18:36

docs: define authorization schema discovery

e68d719

docs: render decision section numbers

0d57b94

mariajgrimaldi force-pushed the MJG/authz-schema/discovery branch from 8454483 to 0d57b94 Compare September 1, 2026 16:37

BryanttV mentioned this pull request Sep 2, 2026

Plugin Discovery Mechanism and Aggregation #433

Open

mariajgrimaldi added 5 commits September 2, 2026 18:46

docs: clarify authorization schema discovery

3fa4583

docs: clarify schema entry point discovery

349b9f5

docs: explain schema entry point discovery

e496708

docs: add schema entry point example

f9005c9

docs: document application and Tutor schema discovery

49c8d4c


		An application contributes one or more authz schema resources through a Python entry point defined by ``openedx-authz``. Discovery resolves those resources with ``importlib.resources`` and returns all contributions in a defined order, since Python package discovery order may vary.

		For example, a ``course_authoring`` package can register ``course_authoring.authz:get_schema_resources`` and return ``authz/course_roles.authz.yaml`` and ``authz/course_permissions.authz.yaml``.

Uh oh!

Conversation

mariajgrimaldi commented Aug 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Uh oh!

openedx-webhooks commented Aug 27, 2026

Uh oh!

rodmgwgu left a comment

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!

BryanttV left a comment

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!

5 participants

mariajgrimaldi commented Aug 27, 2026 •

edited

Loading