feat: add authz schema validation

[rodmgwgu]

Problem

An invalid schema must stop a deployment before anything is written, and it must report every problem at once rather than failing on the first one — a deployment operator fixing schema files one error per run is the failure mode to avoid (ADR 0018 §1).

Approach

PLEASE NOTE: jsonschema-based validation hasn't been implemented at this point, this means that some cases like validation of required priority and other fields are not complete. The implementation of the jsonschema validation will cover these, that is tracked by this issue: #459

• openedx_authz/engine/schema/validation.py — SchemaValidator, ValidationIssue
• openedx_authz/tests/schema/test_validation.py

Two entry points, matching the two things that can only be checked at different stages: validate() covers each document and the document set (identifier shape, required fields, duplicates), and validate_compiled() covers the rules only a resolved schema can answer (a role referencing a permission that does not exist, a permission in an unknown category). Issues are collected and returned with their source, so a caller can report all of them; SchemaValidationError carries the full list.

Manual testing instructions

pytest openedx_authz/tests/schema/

Rollback plan

Revert this PR. Nothing consumes the validator yet, so the revert is inert.

Retro compatibility

No authorization behavior changes. No models, no migration, no automatic code path.

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 (4/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. This PR — schema validation (base: rod/authz-schema-compiler)
5. rod/authz-schema-models — definition models + migration
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

Validation is stacked on compilation, not the reverse: validate_compiled() takes a CompiledSchema. In the lifecycle the validate phase still runs before compile for document-level rules, and after it for the resolved-schema rules.

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 compilation #476; no migration. JSON Schema validation against authz-schema-v1.json is tracked separately in Extend schema loader validation to use schema reference defined in #431 #459

[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]

We're passing several of these structures around by reference and modifying them directly. Could some of this state live on the SchemaValidator instance instead? Maybe issues as well.

My thought process is that documents and the indexes we build from them are used across multiple validation steps, and right now we pass them through several methods and mutate them along the way. I wonder if keeping the state for a validation run on the validator instance would make it a bit easier to manage and reduce the amount of arguments we need to pass around.

Just a thought though, I'm not completely sure how it would look in practice.

[rodmgwgu]

I did some exploring and one issue of making the state live in SchemaValidator is that it would break the pattern that is already being used on all the other modules (they are stateless).

One potential alternative would be to define an internal dataclass that holds all the "state" and we only pass that everywhere.

What do you think, would this be worth a try?

[mariajgrimaldi]

I think this is more about the pros and cons of keeping it stateless, as it is now, versus making it stateful by instantiating it or making it part of the class. If this is a deliberate design decision, I think it would be useful to define it as such.

[mariajgrimaldi]

This looks good to me! Thanks so much for addressing my comments and for explaining the decisions behind it as well. I think the main thing left is documenting those deliberate decisions somewhere so we have a clearer picture of the overall architecture and the reasoning behind it.

Thanks so much :)

[mariajgrimaldi]

[question] How should priority apply to conflicting base definitions? This is not specified in the ADRs or schema reference.

I tested two files defining the same category, permission, and role with different metadata. One had priority 100 and the other priority 200. The command rejected all three definitions:

Conflicting category definition for 'acceptance_category'.
Conflicting permission definition for 'acceptance.view'.
Conflicting role definition for 'acceptance_editor'.
Schema validation failed with 3 error(s).

The compiler behavior and its test expect the priority 200 definitions to win, but the full command rejects them before that happens. Could we decide which behavior we want and make it consistent?

[rodmgwgu]

Good catch, I see that the ADR 0017 specifies: Priority resolves conflicts between role extensions; it does not apply to individual permissions or control how roles or permissions appear in the UI.

So the current overall behavior would be consistent with that.

Do you see any use case where we may want to support priority on base definitions? if so, we could define it and change it to work as that, or just remove the priority logic for those in the compiler.