docs: add authorization schema reference

docs/decisions/0017-static-authorization-schema.rst

@@ -23,6 +23,8 @@ The authz schema is a versioned YAML format for static permissions, permission c
 
 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
 =============================
 

docs/decisions/0018-authorization-schema-lifecycle.rst

@@ -59,7 +59,7 @@ For example, the loader may update the static row that links ``courses.view_cour
 
 Static and dynamic roles share the same set of names, so neither kind can reuse a name that already exists. The dynamic role API rejects a name used by a static role, and deployment stops when a new static role conflicts with an existing dynamic role.
 
-Because this ADR covers the lifecycle of static definitions, it establishes that static role IDs follow the authz schema's naming conventions. Naming conventions for dynamic roles are outside its scope.
+Because this ADR covers the lifecycle of static definitions, it establishes that static role IDs follow the conventions in the :ref:`Authorization Schema Reference`. Naming conventions for dynamic roles are outside its scope.
 
 For example, an administrator cannot create a dynamic ``course_observer`` role when an application already defines a static role with that name. If the dynamic role existed first, a deployment that introduces the static role stops and reports both the contributing package and the conflicting database record, leaving both definitions unchanged.
 

docs/decisions/0019-authorization-schema-discovery.rst

@@ -35,28 +35,26 @@ The registered function returns the package resources that contain its schema:
    def get_schema_resources():
        return ["authz/course_authoring.authz.yaml"]
 
-The compiler loads the ``authz.schema`` entry-point group, calls each registered function, and uses ``importlib.resources`` or a similar mechanism to find the files. It then validates the schemas, compiles them into Casbin rows, and applies them to the database.
+The compiler loads the ``authz.schema`` entry-point group, calls each registered function, and resolves the returned paths with ``importlib.resources``.
 
 If a registered function raises an exception, discovery stops and reports which application failed. This prevents deployment from continuing with an incomplete set of static definitions.
 
-Site operators can contribute a schema through the ``openedx-authz-schema`` Tutor patch:
+Site operators can use a Tutor patch to add a schema that belongs to their deployment:
 
-.. code-block:: yaml
-
-   name: openedx-authz-overrides
-   version: 0.1.0
+.. code-block:: python
 
-   patches:
-     openedx-authz-schema: |
-       schema_version: "1.0"
-       priority: 200
+   from tutor import hooks
 
-       role_extensions:
-         - role: course_editor
-           add_permissions:
-             - courses.export_course
+   hooks.Filters.ENV_PATCHES.add_item((
+       "openedx-common-settings",
+       """
+   OPENEDX_AUTHZ_SCHEMA_RESOURCES += [
+       ("site_authorization", "authz/site.authz.yaml"),
+   ]
+   """,
+   ))
 
-The compiler combines schemas from application entry points and Tutor patches in a defined order because discovery order may vary.
+Both options pass package names and resource paths to the same compiler. The compiler returns all contributions in a defined order because package discovery order may vary.
 
 2. Static source information
 ============================

docs/decisions/0023-extend-static-roles.rst

@@ -19,7 +19,7 @@ Decision
 1. Role extension fields
 ========================
 
-A ``role_extensions`` entry identifies an existing static role with ``role`` and changes only the fields included in the entry. It may use:
+A ``role_extensions`` entry identifies an existing static role with ``role`` and changes only the fields included in the entry. The :ref:`Authorization Schema Reference` describes these fields and includes complete examples for applications and Tutor configuration. An entry may use:
 
 * ``add_permissions`` to add complete permission IDs;
 * ``remove_permissions`` to remove complete permission IDs;
@@ -131,6 +131,7 @@ References
 * `ADR 0017`_
 * `ADR 0018`_
 * `ADR 0019`_
+* :ref:`Authorization Schema Reference`
 * `Tutor plugin development`_
 
 .. _ADR 0017: 0017-static-authorization-schema.rst