feat: add authz schema definition models

[rodmgwgu]

Problem

Compiled definitions and their provenance need first-class tables. Casbin p rows alone cannot answer which distribution contributed a role, whether a contribution was a base definition or an extension, or which rows the schema loader owns — and ownership is what makes later pruning safe instead of guesswork (ADR 0025).

Approach

• openedx_authz/models/schema.py — definition tables (permission categories, permission definitions, role definitions, role-permission grants) and provenance tables (schema sources plus one source-link table per definition kind)
• openedx_authz/migrations/0011_authz_schema_definitions.py — additive migration
• openedx_authz/models/__init__.py — export the new module

Source attribution is recorded at the role-permission grain, so contributions from different applications to the same role stay distinguishable. The query helpers (origins_for_role, origins_for_permission, origins_for_category, origin_for_role_permission) land with the models.

Nothing writes to these tables in this PR — the applier does, in 7/8.

Manual testing instructions

pytest openedx_authz/tests/

Confirm the migration is complete and applies cleanly:

./manage.py makemigrations --check --dry-run openedx_authz   # No changes detected
tutor dev run cms ./manage.py cms migrate openedx_authz

Rollback plan

Revert this PR and run the reverse migration if it was applied. The migration is purely additive — it creates new tables and alters none — so a revert cannot affect existing data.

Retro compatibility

No authorization behavior changes. The tables are created empty and nothing reads or writes them until the applier lands.

AI Usage

Kiro was used to assist on feature planning and implementation. Implementation was done step by step with human guidance and validation, based on the ADRs.

---

Stack (5/8) — #446 split into reviewable pieces. Bases chain bottom-up; merge in order.

1. feat: add authz schema discovery #474 — schema discovery
2. feat: add authz schema loading #475 — schema loading
3. feat: add authz schema compilation #476 — schema compilation
4. feat: add authz schema validation #477 — schema validation
5. This PR — definition models + migration (base: rod/authz-schema-validator)
6. rod/authz-schema-renderer — policy renderer
7. rod/authz-schema-applier — schema applier
8. feat: add authz schema pipeline and load_authz_schema command #446 — pipeline + load_authz_schema command, version bump and changelog

Merge checklist:

• Version bumped — deferred to 8/8 so the stack does not conflict on every restack
• Changelog record added — deferred to 8/8
• Documentation updated (not only docstrings) — covered by the already-merged ADRs
• Fixup commits are squashed away
• Unit tests added/updated
• Manual testing instructions provided
• Noted any: Concerns, dependencies, migration issues, deadlines, tickets — depends on feat: add authz schema validation #477; contains a DB migration (0011, additive). If another 0011 lands on main first this needs renumbering

[openedx-webhooks]

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:

• Overview of Review Process for Community Contributions
• Pull Request Status Guide
• Making changes to your pull request

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.

[mariajgrimaldi]

A few comments for you to review! This will probably will need to be updated according the changes down the stack, mainly the model fields.

[mariajgrimaldi]

Maybe we can create an abstract model for managing these timestamps

[rodmgwgu]

Good idea, added an abstract TimeStampedModel.

[mariajgrimaldi]

nit: I wouldn't call this a grant, since technically it doesn't grant any permission. This adds semantic meaning to each Casbin row, but the actual permission attribution is still managed by Casbin. It might be a bit misleading as is.

[rodmgwgu]

Reworded to make it clearer.

[mariajgrimaldi]

One blocking comment left to review! Thanks so much for all of this :))

[mariajgrimaldi]

Do we expect them to change or be managed independently very often?

Right now they seem mostly like provenance for the compiled schema, and they would usually only change during deployment. That's why I'm a bit skeptical about having them as separate persistent models.

Is the main reason to make them models so we can query/remove contributions by source? And if a source stops contributing anything, do we expect to remove it?

[rodmgwgu]

At this point the main reason for having this as a model is to track the provenance of the definitions.

Originally I planned these to be able to correctly detect changes on these sources when they occur (for example, a role is removed from one yaml, this is how we would know that we should try to remove that role from the instance). However the final implementation ended up not using this, and just doing a diff on the compiled vs current state.

So at this point it can be used for debugging to understand where a definition came from.

It could also be used to expose provenance information in the API if required, but this is not implemented nor planned at this point.

This same mechanism could also be used in the future for tracking custom dynamic roles, although it will require changes to the AuthzSchemaSource to differentiate these.

Currently there is no mechanism for removing sources, but I would think we should plan on adding one to avoid stale data.

I'd vote to keep these models. they are write-only today with no runtime cost, but the provenance is derived at compile time and hard to reconstruct later. Since ADR 0025 already anticipates future uses, retaining it now is cheaper than rebuilding it when we need it.

What do you think?