Add `hidden` property to permission categories and permissions

Open
#632 0 comments 0 reactions 1 assignee View on GitHub

Maintainers usually reply within 1 day

@BryanttV is already working on this.

Since Nov 17, 2026.

  • #633 by @BryanttV — merged
  • #634 by @BryanttV — open

Assessment

This issue has not been assessed yet.

Description

Description

Static roles already support a hidden flag (ADR 0023) that removes a role from normal discovery and selection interfaces without deleting it or changing permission checks. Permission categories and permissions have no equivalent. Operators and applications cannot keep a permission or category defined in the schema while omitting it from the catalog that UIs consume (for example, one that is deprecated, experimental, or not meant to be assigned directly).

Adding the same flag to categories and permissions lets deployments control what is surfaced in the role/permission catalog while keeping the definitions, existing role grants, and enforcement intact.

Current Behavior
  • hidden is only supported on roles ($defs/role and $defs/role_extension in authz-schema-v1.json) and persisted in AuthzRoleDefinition.hidden.
  • permission_categories and permissions entries in the schema do not accept hidden, and AuthzPermissionCategory / AuthzPermissionDefinition have no such column.
  • The scope-type catalog endpoint (ADR 0028) returns every category and permission used by the requested scope types, regardless of whether they should be exposed.
Expected Behavior
  • Categories and permissions accept an optional boolean hidden field in the authorization schema (default false), with the same semantics as for roles: hidden items are omitted from normal discovery APIs and selection UIs, but are not deleted, do not lose existing role grants, and do not change permission checks.
  • The compiled schema, source tracking, and database persist the flag, and changing it is reported as an update when applying a schema.
  • The role/permission catalog API omits hidden categories and hidden permissions (and does not return a category whose permissions are all hidden).
Acceptance Criteria
  • authz-schema-v1.json accepts an optional boolean hidden (default false) on category and permission definitions, and the schema reference docs are regenerated.
  • AuthzPermissionCategory and AuthzPermissionDefinition store hidden, with a migration that defaults existing rows to false.
  • The schema compiler, storage, and load_authz_schema / apply reporting persist the flag and report a changed hidden value as an update.
  • The catalog endpoint excludes hidden categories and hidden permissions, and the API contract is documented.
  • Hiding a permission or category does not remove existing role-permission relationships and does not alter authorization checks.
  • Behavior for a role that references a hidden permission is defined and covered by a test.
  • Tests cover schema validation, persistence, clearing the flag, and catalog filtering.
  • Documentation (ADR or ADR update, schema reference, CHANGELOG) is updated.

Related: ADR 0023 (hidden roles), ADR 0025 (source tracking), ADR 0028 (role catalog API contract).

Dominant language
Python
Stars
0
Forks
10
Avg merge
5d 11h
Merged PRs (30d)
25

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from openedx/openedx-authz

All issues in openedx/openedx-authz

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.