docs: add ADR for authorization schema source tracking by rodmgwgu · Pull Request #444 · openedx/openedx-authz

rodmgwgu · 2026-09-10T18:17:39Z

Problem

The authorization schema loading pipeline needs a documented decision record explaining how schema definitions and their source are tracked before the implementation lands.

Approach

Adds ADR 0025-authorization-schema-source-tracking.rst describing the source-tracking design.

AI Usage

Kiro was used to assist on research and write the ADR with human guidance and validation.

Stack (1/3) — split from a single combined commit for reviewability:

This PR — ADR doc (base: main)
rod/authz-schema-files — authz schema YAML files (base: this branch)
rod/authz-schema-loader — schema loading pipeline (base: PR 2)

Merge checklist:

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

Adds 0025 ADR describing how authorization schema definitions and their source are tracked. Part 1 of the schema loading pipeline stack.

openedx-webhooks · 2026-09-10T18:17:46Z

Thanks for the pull request, @rodmgwgu!

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.

BryanttV

Thanks! I have a few questions.

BryanttV · 2026-09-11T18:34:51Z

+********
+
+1. Store compiled definitions and their sources in dedicated tables
+====================================================================


Are these tables intended exclusively for static roles? Or could they perhaps be used for the future implementation of dynamic roles?

They could be used for dynamic roles, but we will probably need to add some fields to identify these vs the static ones. For now I'm considering that out of scope for this ADR

Added clarification that this ADR is specific for static policy definitions.

BryanttV · 2026-09-11T19:42:47Z

+4. Attribution is queryable and may be exposed by the API
+=========================================================
+
+Given any role or permission, its origin can be queried from the definition and link tables — for
+a role as a whole, for a single permission, or for a specific role-permission grant. The
+authorization definition API (`ADR 0021`_) may expose these sources so a client such as the
+Administrative Console can show which application contributed a role or permission. Exposing the
+sources is an additive, optional API change and is not required by this decision.


The proposal is to obtain role and permission information from the tables, rather than from the schema files, correct?

How would display fields (which should be compatible with translations) be handled, given that ADR 20 proposes a mechanism for reading from YAML schema files?

Yes, on runtime the permission information that the API will serve will come from these tables.

These tables are updated from the yaml schema files on deployment (via the manage.py command), so the source of truth will be the YAML files. So the translations should work the same as the strings will be the same.

Added a paragraph explaining this

BryanttV · 2026-09-11T19:56:18Z

+6. Adopt pre-existing policy rows; leave unmanaged rows untouched
+=================================================================
+
+On the first deployment after this feature ships, existing Casbin ``p`` rows are adopted rather


Is this just for the first deployment? Or should it be a permanent behavior?

I'm thinking It will be a permanent behavior, do you see any reason not to?

I'll update the text to make this clearer, thanks.

mariajgrimaldi · 2026-09-14T11:37:55Z

+* a permission-category table (stable id and display fields);
+* a permission-definition table (namespace and name forming the complete permission id, plus
+  display fields, category, and supported scopes);
+* a role-definition table (stable role id, display fields, supported scopes, and the ``hidden``
+  flag from `ADR 0023`_); and
+* a role-permission table holding one row per ``(role, permission, scope)`` relationship.


Can we include how each of these tables will be used? I think the storage approach for both dynamic and static rules should be covered in a separate ADR. Also that ADR should also explain how these tables relate to ExtendedCasbinRule and its current fields. I think it'd be a good continuation of: #422 (store, however we want to call the lifecycle phase)

What do you think?

Originally, I thought on using ExtendedCasbinRule for tracking this, however decided on not using it because it is more geared towards assignments (g rules), and is one-to-one related to the corresponding CasbinRule, while we could have more than one contributing source for a single role or permission.

Also to avoid confusions and keep concerns separated.

mariajgrimaldi · 2026-09-14T12:11:14Z

+2. Attribute sources through an explicit many-to-many link
+===========================================================
+
+A source table records each distinct contribution. Its identity is ``(distribution, module)`` —


What would be the source for new roles specified via the API?

I wasn't thinking on dynamic roles at the time of writing this, It came from necessity when implementing the loader pipeline. Perhaps I should specify that this ADR scope is only for static definitions and revisit this on another ADR for dynamic ones?

Added clarification that this ADR is specific for static policy definitions.

mariajgrimaldi · 2026-09-14T12:15:58Z

+
+Every definition and every role-permission relationship links to one or more sources through
+explicit link tables. Each link records whether the contribution was a base definition or an
+extension, and the contributing file's priority so the winning metadata source is derivable. The


So we're proposing here to store sources but not their metadata? In the porposed lifecycle: #422 we defined that this would be done during compilation time (a deployment task) so the metadata is not derivable but is stored directly. The versioning could be managed as a history table to maintain a change audit trail.

Also as a side note: I only expanded on the discovery & loading phase in #423, since it was the most immediate problem, not necessarily to solve but to provide some direction. I think it would make sense to expand on the remaining phases (like compilation which this decision refers to, apply which relates to how this will be stored and so on) as we implement them in their own dedicated ADRs.

I wasn't thinking on keeping a full audit trail here, that's a good point that needs to be added.

The current proposal is mainly for comparing the previously applied schema vs the one that is being applied now.

For example: let's say that we had module-a and module-b, we already compiled and stored the schemas from both modules. Then, we deploy a new version which modifies module-a schema and/or removes module-b.

The stored definitions will help us detect what changed, and what needs to be updated and removed, and be able to explain the why of these changes.

On the implementation I'm working on in #446, changes can be detected by comparing source file hashes, which are stored in the database.

mariajgrimaldi · 2026-09-14T13:08:28Z

+Because attribution lives at the role-permission grain, a core grant and a module-added grant on
+the same role remain individually attributed. For ``course_admin``:


nit: I think we should shared vocabulary for this. Maybe we can call the built-in roles built-in (come with deployment) and user-defined those added by extensions, or any other alternative

agree, this is confusing, on other ADRs we were talking about static vs dynamic right? I think we can keep those, I'll update the text to reflect that.

Mmm after reading it again, the actual distinction we want here is the "roles that come with Open edX" vs "roles added by another module or plugin", however, technically there shouldn't be any difference between roles that come with Open edX and the ones added by a module, as we will be using the same mechanism to register them anyways.

I'l revise this text to make this clearer.

docs: add ADR for authorization schema source tracking

cadcc9c

Adds 0025 ADR describing how authorization schema definitions and their source are tracked. Part 1 of the schema loading pipeline stack.

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 Sep 10, 2026

openedx-webhooks added this to Contributions Sep 10, 2026

github-project-automation Bot moved this to Needs Triage in Contributions Sep 10, 2026

This was referenced Sep 10, 2026

feat: add authz schema definition files #445

Open

feat: implement authz schema loading pipeline #446

Draft

rodmgwgu requested review from BryanttV, carlos-marquez-wgu, mariajgrimaldi and wgu-taylor-payne September 10, 2026 18:34

rodmgwgu mentioned this pull request Sep 10, 2026

[WIP] feat: Implemented schema loading pipeline #440

Closed

7 tasks

rodmgwgu added this pull request to stack #447 September 10, 2026 18:40

BryanttV linked an issue Sep 11, 2026 that may be closed by this pull request

Core Loader, Compilation, and Definition Validation #410

Open

BryanttV removed a link to an issue Sep 11, 2026

Core Loader, Compilation, and Definition Validation #410

Open

BryanttV linked an issue Sep 11, 2026 that may be closed by this pull request

Policy contribution attribution #412

Open

BryanttV reviewed Sep 11, 2026

View reviewed changes

mariajgrimaldi reviewed Sep 14, 2026

View reviewed changes

rodmgwgu added 2 commits September 15, 2026 16:09

squash!: Improvements based on comments

408aca5

squash!: Improve table definitions

c06af6e

		Because attribution lives at the role-permission grain, a core grant and a module-added grant on
		the same role remain individually attributed. For ``course_admin``:

Uh oh!

Conversation

rodmgwgu commented Sep 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Problem

Approach

AI Usage

Uh oh!

openedx-webhooks commented Sep 10, 2026

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!

rodmgwgu Sep 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

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

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!

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

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

rodmgwgu commented Sep 10, 2026 •

edited

Loading

rodmgwgu Sep 14, 2026 •

edited

Loading

mariajgrimaldi Sep 14, 2026 •

edited

Loading

mariajgrimaldi Sep 14, 2026 •

edited

Loading