docs: add authorization schema reference

MANIFEST.in

@@ -3,4 +3,4 @@ include LICENSE.txt
 include README.rst
 include requirements/base.in
 include requirements/constraints.txt
-recursive-include openedx_authz *.html *.png *.gif *.js *.css *.jpg *.jpeg *.svg *.conf *.policy
+recursive-include openedx_authz *.html *.png *.gif *.js *.css *.jpg *.jpeg *.svg *.conf *.policy *.json

docs/conf.py

@@ -71,6 +71,7 @@ def get_version(*file_paths):
     "sphinx.ext.intersphinx",
     "sphinx.ext.ifconfig",
     "sphinx.ext.napoleon",
+    "sphinx-jsonschema",
 ]
 
 # A list of warning types to suppress arbitrary warning messages.
@@ -570,6 +571,7 @@ def on_init(app):  # pylint: disable=unused-argument
             docs_path,
             os.path.join(root_path, "openedx_authz"),
             os.path.join(root_path, "openedx_authz/migrations"),
+            os.path.join(root_path, "openedx_authz/schema"),
             os.path.join(root_path, "openedx_authz/tests"),
         ],
         env=env

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

@@ -19,10 +19,12 @@ 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 YAML Schema for this format so that editors, CI, and the compiler all apply the same field and validation rules.
+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
 =============================
 
@@ -159,11 +161,11 @@ References
 * `ADR 0016`_
 * `ADR 0023`_
 * `Casbin adapters`_
-* `ASDF YAML Schema`_
+* `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
-.. _ASDF YAML Schema: https://www.asdf-format.org/projects/asdf-standard/en/1.0.2/schemas/yaml_schema.html
+.. _JSON Schema: https://json-schema.org/draft/2020-12/json-schema-core
 .. _Paragon icons: https://paragon-openedx.netlify.app/components/icon/

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

@@ -62,7 +62,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/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