0017: Define Static Roles and Permissions in an Authorization Schema
####################################################################

Status
******

**Draft**

Context
*******

`ADR 0016`_ defines static roles in the authz schema and dynamic roles in the authz model, which the API manages through the Casbin adapter. Today, however, static roles and permissions are spread across Python constants, Python role mappings, ``authz.policy``, and frontend code. A developer who adds a role or permission must therefore update several representations, including a separate copy of its display information in the frontend.

Casbin remains the authorization engine, and its adapter continues to read and write policy rows. The authz schema adds the Open edX format that Casbin does not provide, allowing an application to declare stable identifiers, supported scopes, role permissions, and display information in one place. During deployment, the schema is compiled into Casbin rows, while the API makes the display information available to the frontend.

Decision
********

1. Schema format and boundary
=============================

The authz schema is a versioned YAML format for static permissions, permission categories, roles, and changes to existing roles. Every file declares ``schema_version`` and ``priority``, which apply to all definitions in that file. Priority is used when role extensions conflict. Open edX publishes a :download:`machine-readable JSON Schema <../../openedx_authz/schema/authz-schema-v1.json>` for this format so that editors, CI, and the compiler all apply the same field and validation rules.

The existing static role and permission definitions in Python modules and ``authz.policy`` will move into the schema. Once this migration is complete, the schema becomes the source for static definitions, so developers add a new role or permission there without duplicating it in Python constants or policy files.

The :ref:`Authorization Schema Reference` describes every field, the naming conventions, and complete configuration examples.

2. Permissions and categories
=============================

A permission contains:

* ``namespace`` and ``name``, which form the stable identifier used by application checks, such as ``courses.view_course``;
* the scope namespaces where it can apply;
* a normalized permission category; and
* ``display_name``, ``description``, and an optional Paragon icon name.

For example:

.. code-block:: yaml

   permission_categories:
     - id: course_content
       display_name: Course content
       description: Permissions for viewing and editing course content.
       icon: Article

   permissions:
     - namespace: courses
       name: view_course
       display_name: View course
       description: View course configuration and content.
       category: course_content
       scopes:
         - course-v1
       icon: Visibility
     - namespace: courses
       name: delete_course
       display_name: Delete course
       description: Delete a course.
       category: course_content
       scopes:
         - course-v1
       icon: Delete

Here, ``course_content`` groups the two permissions for display. The complete permission IDs are ``courses.view_course`` and ``courses.delete_course``, while ``course-v1`` is the scope namespace where they apply. Application code uses the complete permission ID, so changing ``display_name`` does not change permission checks.

3. Roles and role extensions
============================

A role contains a stable identifier, display name, description, supported scope namespaces, and a list of complete permission identifiers. When an application needs to change an existing role, it uses ``role_extensions``. An extension may add or remove permissions and may replace the role's display name or description. `ADR 0023`_ defines the detailed behavior of role extensions.

Version 1 does not define display order for roles, permissions, or categories. Clients may sort them alphabetically or apply another order that suits their interface.

.. code-block:: yaml

   schema_version: "1.0"
   priority: 100

   roles:
     - id: course_observer
       display_name: Course observer
       description: Can review a course without changing it.
       scopes:
         - course-v1
       permissions:
         - courses.view_course

   role_extensions:
     - role: course_admin
       add_permissions:
         - courses.delete_course

In these examples, ``courses.view_course`` appears under ``course_content`` in the UI and belongs to the new ``course_observer`` role. The ``role_extensions`` entry adds ``courses.delete_course`` to the existing ``course_admin`` role. The compiler can render the observer's role-permission relationship as:

.. code-block:: text

   p, role^course_observer, act^courses.view_course, course-v1^*, allow

The compiler also creates a row that links ``course_admin`` to ``courses.delete_course``. Priority resolves conflicts between role extensions; it does not apply to individual permissions or control how roles or permissions appear in the UI.

The schema contains static definitions, while user assignments and user-defined roles stay in the application database. Casbin's ``model.conf`` and matcher also remain owned by ``openedx-authz``.

4. Validation and conflicts
===========================

Validation first checks each file against the published schema. It rejects:

* invalid YAML, unknown fields, missing required fields, and values with the wrong type;
* unsupported schema versions;
* permission namespaces and names, role IDs, or category IDs that do not use lowercase ASCII ``snake_case``;
* icon names that don't follow the available icons from ``@openedx/paragon/icons``; and
* display fields that exceed the agreed size limits.

When Paragon renames or removes an icon, the schema follows the same deprecation process as other consumers of ``@openedx/paragon/icons``.

After loading every file, validation checks the combined definitions. It rejects:

* references to permissions or categories that do not exist;
* a role extension whose role does not exist in the combined definitions;
* a role used in a scope where one of its permissions cannot apply;
* conflicting static definitions;
* conflicting role extensions with the same priority; and
* unsupported combinations of schema versions.

The validator warns about duplicate definitions, including identical definitions, and about role extensions that do not take effect because another file has a higher priority. The highest-priority role extension resolves a conflict. If several files add the same permission to the same role, the compiler creates one Casbin row and records each contributing source.

Unit tests can load schema fixtures into an in-memory Casbin enforcer and check allowed and denied requests. This follows the model-testing approach used by OpenFGA and the schema assertions used by SpiceDB, while keeping the tests in normal application test suites.

Consequences
************

* Applications declare static permission identifiers, role-to-permission assignments, and UI fields in the same YAML format.
* Application checks continue to use stable permission identifiers and do not depend on role names.
* Application clients can read the compiled definitions from the API and remove its copy.
* Schema validation needs both per-file checks and checks across all files, including conflicts and role extensions.
* Role extensions can change the permissions assigned to built-in roles. Deployment must report them clearly, and the operator remains responsible for approving them.
* Version 1 excludes permission implication and role inheritance.

Rejected Alternatives
*********************

Raw Casbin policy files
=======================

They express the rows Casbin needs for permission checks but omit the display fields and source information required by users and applications.

Python constants and role mappings
==================================

Definitions would remain split across backend and frontend code. Applications would also need to change ``openedx-authz`` to add definitions they own.

Embedded categories on every permission
=======================================

Repeating category labels makes localization and consistent presentation harder. A normalized category gives permissions one stable grouping reference.

References
**********

* `ADR 0016`_
* `ADR 0023`_
* `Casbin adapters`_
* `JSON Schema`_
* `Paragon icons`_

.. _ADR 0016: 0016-static-and-dynamic-roles.rst
.. _ADR 0023: https://github.com/openedx/openedx-authz/pull/430
.. _Casbin adapters: https://v3.casbin.org/docs/adapters
.. _JSON Schema: https://json-schema.org/draft/2020-12/json-schema-core
.. _Paragon icons: https://paragon-openedx.netlify.app/components/icon/