openedx-authz 2.0.0__tar.gz → 2.2.0__tar.gz

{openedx_authz-2.0.0 → openedx_authz-2.2.0}/.github/workflows/ci.yml

@@ -21,7 +21,7 @@ jobs:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Install uv
-        uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
+        uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
         with:
           enable-cache: true
           python-version: ${{ matrix.python-version }}

{openedx_authz-2.0.0 → openedx_authz-2.2.0}/.github/workflows/release.yml

@@ -87,4 +87,4 @@ jobs:
         path: dist/
 
     - name: Publish to PyPI
-      uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+      uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3

{openedx_authz-2.0.0/src/openedx_authz.egg-info → openedx_authz-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openedx-authz
-Version: 2.0.0
+Version: 2.2.0
 Summary: Open edX AuthZ provides the architecture and foundations of the authorization framework.
 Author-email: Open edX Project <oscm@openedx.org>
 License-Expression: AGPL-3.0-or-later
@@ -28,6 +28,7 @@ Requires-Dist: edx-django-utils
 Requires-Dist: edx-drf-extensions
 Requires-Dist: edx-opaque-keys
 Requires-Dist: edx-organizations
+Requires-Dist: jsonschema>=4.0
 Requires-Dist: openedx-atlas
 Requires-Dist: openedx-events
 Requires-Dist: openedx-filters>=3.15.0

{openedx_authz-2.0.0 → openedx_authz-2.2.0}/docs/decisions/0017-static-authorization-schema.rst

@@ -19,7 +19,7 @@ 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 only when role extensions conflict; it does not resolve conflicting base definitions (see `ADR 0031`_). Open edX publishes a :download:`machine-readable JSON Schema <../../src/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 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 only when role extensions conflict; it does not resolve conflicting base definitions (see `ADR 0031`_). Open edX publishes a :download:`machine-readable JSON Schema <../../src/openedx_authz/engine/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.
 
@@ -155,6 +155,12 @@ Embedded categories on every permission
 
 Repeating category labels makes localization and consistent presentation harder. A normalized category gives permissions one stable grouping reference.
 
+Addendum: 2026-10-20
+********************
+
+The machine-readable JSON Schema now lives with its validation engine at
+:download:`authz-schema-v1.json <../../src/openedx_authz/engine/schema/authz-schema-v1.json>`.
+
 References
 **********
 

{openedx_authz-2.0.0 → openedx_authz-2.2.0}/docs/decisions/0018-authorization-schema-lifecycle.rst

@@ -107,6 +107,25 @@ Two limitations are accepted:
 * **Single-database assumption.** Serialization holds only when the generated policy and the lock live in the same database. The engine already assumes one database for its policy storage, so this is consistent with the rest of the system.
 * **Blocking wait without observability.** A second apply waits for the first with no timeout and no distinct signal, so a blocked apply is operationally indistinguishable from a slow one. This is acceptable because apply runs at deployment time, not on the request path.
 
+Addendum: Separate structural and semantic validation
+======================================================
+
+**2026-10-20**
+
+Schema processing separates parsing, structural validation, typed loading, and semantic validation into ordered phases.
+
+The lifecycle begins with these phases:
+
+1. **Discover** identifies the contributed schema resources.
+2. **Parse** reads each resource as YAML and preserves the resulting value with its source information.
+3. **Validate structure** checks every parsed value against the configured JSON Schema. The pipeline reports all structural errors and stops when it finds any.
+4. **Load** constructs typed schema definitions from structurally valid mappings.
+5. **Validate semantics** checks relationships across definitions, conflicts between contributions, supported scopes, and values that depend on application data such as the vendored Paragon icon names.
+
+Compile, render, apply, and consume keep the responsibilities defined above. Typed loading and semantic validation do not run when structural validation fails. This ordering lets JSON Schema report malformed collection shapes and value types before typed construction assumes those structures are valid.
+
+The separation adds an intermediate parsed-document representation and another explicit pipeline boundary. Callers that previously treated loading as both YAML parsing and typed construction must use the corresponding phase for the representation they need.
+
 Consequences
 ************
 

{openedx_authz-2.0.0 → openedx_authz-2.2.0}/docs/decisions/0030-tutor-implementation-authz-schema-discovery.rst

@@ -102,7 +102,7 @@ Example rendered file with two plugin contributions:
 Schemas discovered through ``OPENEDX_AUTHZ_SCHEMA_FILES`` have no Python package or module. To satisfy the source-tracking requirements of `ADR 0025`_, their source record uses:
 
 * ``distribution`` = ``<tutor-patch>`` — a sentinel value that is an invalid Python package name, guaranteeing no collision with any installed distribution.
-* ``module`` = ``null`` — filesystem sources have no owning Python module, and using the absolute path would be inconsistent with the field's semantics elsewhere in the model.
+* ``module`` = the absolute filesystem path of the schema file (e.g. ``/openedx/config/authz-schema.yml``). Filesystem sources have no owning Python module, but reusing the path here keeps the ``(distribution, module)`` unique constraint enforceable and avoids the ``NULL``-handling complications that a ``null`` value would introduce across the ORM, migrations, and source-identity logic.
 * ``resource_path`` = the absolute filesystem path of the schema file (e.g. ``/openedx/config/authz-schema.yml``).
 * ``distribution_version`` = ``0.0.0`` — a sentinel value, since filesystem sources carry no package version.
 

openedx_authz-2.2.0/docs/references/authorization-schema-json.rst

@@ -0,0 +1,118 @@
+.. _Generated Authorization Schema:
+
+Generated Authorization Schema
+##############################
+
+This page renders the exact validation rules from the :download:`authz JSON Schema <../../src/openedx_authz/engine/schema/authz-schema-v1.json>`. See the :doc:`Authorization Schema Reference <authorization-schema>` for guidance, examples, and validation performed by the compiler across schema contributions.
+
+Top-level fields
+****************
+
+.. jsonschema:: ../../src/openedx_authz/engine/schema/authz-schema-v1.json#/properties/schema_version
+   :lift_description:
+
+.. jsonschema:: ../../src/openedx_authz/engine/schema/authz-schema-v1.json#/properties/priority
+   :lift_description:
+
+.. jsonschema:: ../../src/openedx_authz/engine/schema/authz-schema-v1.json#/properties/permission_categories
+   :lift_description:
+   :hide_key: /items
+
+.. jsonschema:: ../../src/openedx_authz/engine/schema/authz-schema-v1.json#/properties/permissions
+   :lift_description:
+   :hide_key: /items
+
+.. jsonschema:: ../../src/openedx_authz/engine/schema/authz-schema-v1.json#/properties/roles
+   :lift_description:
+   :hide_key: /items
+
+.. jsonschema:: ../../src/openedx_authz/engine/schema/authz-schema-v1.json#/properties/role_extensions
+   :lift_description:
+   :hide_key: /items
+
+Permission category fields
+**************************
+
+.. jsonschema:: ../../src/openedx_authz/engine/schema/authz-schema-v1.json#/$defs/permission_category/properties/id
+   :lift_description:
+
+.. jsonschema:: ../../src/openedx_authz/engine/schema/authz-schema-v1.json#/$defs/permission_category/properties/display_name
+   :lift_description:
+
+.. jsonschema:: ../../src/openedx_authz/engine/schema/authz-schema-v1.json#/$defs/permission_category/properties/description
+   :lift_description:
+
+.. jsonschema:: ../../src/openedx_authz/engine/schema/authz-schema-v1.json#/$defs/permission_category/properties/icon
+   :lift_description:
+
+Permission fields
+*****************
+
+.. jsonschema:: ../../src/openedx_authz/engine/schema/authz-schema-v1.json#/$defs/permission/properties/namespace
+   :lift_description:
+
+.. jsonschema:: ../../src/openedx_authz/engine/schema/authz-schema-v1.json#/$defs/permission/properties/name
+   :lift_description:
+
+.. jsonschema:: ../../src/openedx_authz/engine/schema/authz-schema-v1.json#/$defs/permission/properties/display_name
+   :lift_description:
+
+.. jsonschema:: ../../src/openedx_authz/engine/schema/authz-schema-v1.json#/$defs/permission/properties/description
+   :lift_description:
+
+.. jsonschema:: ../../src/openedx_authz/engine/schema/authz-schema-v1.json#/$defs/permission/properties/category_id
+   :lift_description:
+
+.. jsonschema:: ../../src/openedx_authz/engine/schema/authz-schema-v1.json#/$defs/permission/properties/scopes
+   :lift_description:
+
+.. jsonschema:: ../../src/openedx_authz/engine/schema/authz-schema-v1.json#/$defs/permission/properties/icon
+   :lift_description:
+
+Role fields
+***********
+
+.. jsonschema:: ../../src/openedx_authz/engine/schema/authz-schema-v1.json#/$defs/role/properties/id
+   :lift_description:
+
+.. jsonschema:: ../../src/openedx_authz/engine/schema/authz-schema-v1.json#/$defs/role/properties/display_name
+   :lift_description:
+
+.. jsonschema:: ../../src/openedx_authz/engine/schema/authz-schema-v1.json#/$defs/role/properties/description
+   :lift_description:
+
+.. jsonschema:: ../../src/openedx_authz/engine/schema/authz-schema-v1.json#/$defs/role/properties/scopes
+   :lift_description:
+
+.. jsonschema:: ../../src/openedx_authz/engine/schema/authz-schema-v1.json#/$defs/role/properties/permissions
+   :lift_description:
+
+.. jsonschema:: ../../src/openedx_authz/engine/schema/authz-schema-v1.json#/$defs/role/properties/icon
+   :lift_description:
+
+.. jsonschema:: ../../src/openedx_authz/engine/schema/authz-schema-v1.json#/$defs/role/properties/hidden
+   :lift_description:
+
+Role extension fields
+*********************
+
+.. jsonschema:: ../../src/openedx_authz/engine/schema/authz-schema-v1.json#/$defs/role_extension/properties/role_id
+   :lift_description:
+
+.. jsonschema:: ../../src/openedx_authz/engine/schema/authz-schema-v1.json#/$defs/role_extension/properties/add_permissions
+   :lift_description:
+
+.. jsonschema:: ../../src/openedx_authz/engine/schema/authz-schema-v1.json#/$defs/role_extension/properties/remove_permissions
+   :lift_description:
+
+.. jsonschema:: ../../src/openedx_authz/engine/schema/authz-schema-v1.json#/$defs/role_extension/properties/display_name
+   :lift_description:
+
+.. jsonschema:: ../../src/openedx_authz/engine/schema/authz-schema-v1.json#/$defs/role_extension/properties/description
+   :lift_description:
+
+.. jsonschema:: ../../src/openedx_authz/engine/schema/authz-schema-v1.json#/$defs/role_extension/properties/icon
+   :lift_description:
+
+.. jsonschema:: ../../src/openedx_authz/engine/schema/authz-schema-v1.json#/$defs/role_extension/properties/hidden
+   :lift_description:

{openedx_authz-2.0.0 → openedx_authz-2.2.0}/docs/references/authorization-schema.rst

@@ -19,7 +19,7 @@ Use this reference when creating or reviewing an authz schema file. The examples
 Machine-readable schema
 ***********************
 
-The :download:`downloadable authz JSON Schema <../../src/openedx_authz/schema/authz-schema-v1.json>` describes the fields, types, required values, and identifier formats for schema version ``1.0``. You can also :doc:`browse the generated schema <authorization-schema-json>` or `view the schema source <https://github.com/openedx/openedx-authz/blob/main/src/openedx_authz/schema/authz-schema-v1.json>`_. Editors and validation tools can use it to check YAML files because JSON Schema applies to the data represented by both JSON and YAML.
+The :download:`downloadable authz JSON Schema <../../src/openedx_authz/engine/schema/authz-schema-v1.json>` describes the fields, types, required values, and identifier formats for schema version ``1.0``. You can also :doc:`browse the generated schema <authorization-schema-json>` or `view the schema source <https://github.com/openedx/openedx-authz/blob/main/src/openedx_authz/engine/schema/authz-schema-v1.json>`_. Editors and validation tools can use it to check YAML files because JSON Schema applies to the data represented by both JSON and YAML.
 
 The JSON Schema checks the structure of one file. The compiler also checks references across the combined schema, registered scope namespaces, available Paragon icons, and conflicts between contributions.
 

{openedx_authz-2.0.0 → openedx_authz-2.2.0}/pyproject.toml

@@ -36,6 +36,7 @@ dependencies = [
     "edx-drf-extensions",
     "edx-opaque-keys",
     "edx-organizations",
+    "jsonschema>=4.0",
     "openedx-atlas",
     "openedx-events",
     "openedx-filters>=3.15.0",

{openedx_authz-2.0.0 → openedx_authz-2.2.0}/src/openedx_authz/constants/schema.py

@@ -12,6 +12,9 @@ from __future__ import annotations
 
 from enum import Enum
 
+AUTHZ_JSON_SCHEMA_SETTING = "OPENEDX_AUTHZ_JSON_SCHEMA"
+DEFAULT_AUTHZ_JSON_SCHEMA = "openedx_authz.engine.schema/authz-schema-v1.json"
+
 
 class SchemaOriginKind(str, Enum):
     """Whether a schema contribution is a base definition or an extension.

{openedx_authz-2.0.0/src/openedx_authz → openedx_authz-2.2.0/src/openedx_authz/engine}/schema/authz-schema-v1.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://raw.githubusercontent.com/openedx/openedx-authz/main/src/openedx_authz/schema/authz-schema-v1.json",
+  "$id": "https://raw.githubusercontent.com/openedx/openedx-authz/main/src/openedx_authz/engine/schema/authz-schema-v1.json",
   "title": "Open edX Authorization schema",
   "description": "A version 1.0 Open edX authorization schema contribution. Applications and deployment configuration use this format to define static permission categories, permissions, roles, and changes to existing roles.",
   "type": "object",
@@ -121,7 +121,7 @@
     "scope_namespace": {
       "description": "A scope namespace registered by a ScopeData type.",
       "type": "string",
-      "minLength": 1,
+      "pattern": "^[a-z][a-z0-9_-]*$",
       "examples": ["course-v1"]
     },
     "display_name": {
@@ -139,7 +139,7 @@
     "icon": {
       "description": "A case-sensitive icon name exported by @openedx/paragon/icons.",
       "type": "string",
-      "minLength": 1,
+      "pattern": "^[A-Z][A-Za-z0-9]*$",
       "examples": ["Visibility"]
     },
     "permission_list": {

{openedx_authz-2.0.0 → openedx_authz-2.2.0}/src/openedx_authz/engine/schema/discovery.py

@@ -1,7 +1,7 @@
 """Discover static authz schema resources (the ``discover`` step, ADR 0019).
 
-Providers register **directories** (not individual files); the loader reads
-every ``.yaml`` file inside them. Two contribution sources are merged:
+Providers register **directories** of ``.yaml`` files, or individual absolute
+filesystem paths. Three contribution sources are merged:
 
 1. The ``authz.schema`` entry-point group. Each registered callable returns
    directory paths in the package-anchored format below (e.g.
@@ -9,6 +9,10 @@ every ``.yaml`` file inside them. Two contribution sources are merged:
 2. The ``OPENEDX_AUTHZ_SCHEMA_DIRECTORIES`` Django setting, a list of directory
    path strings in the same format. This lets operators and CI contribute
    directories without shipping a package entry point.
+3. The ``OPENEDX_AUTHZ_SCHEMA_FILES`` Django setting, a list of absolute
+   filesystem paths each naming one schema file (ADR 0030). This is the route
+   used by the Tutor ``openedx-authz-schema`` patch to feed a rendered file
+   into discovery without anchoring it on a Python package.
 
 Directory format: these are **not** filesystem paths (neither relative nor
 absolute). Each is a package-anchored ``importlib.resources`` path: the first
@@ -36,12 +40,15 @@ import logging
 from dataclasses import dataclass
 from enum import StrEnum
 from importlib import metadata, resources
+from pathlib import Path
 
 from django.conf import settings
 from django.core.exceptions import ImproperlyConfigured
 
 ENTRY_POINT_GROUP = "authz.schema"
 SETTINGS_DIRECTORIES_NAME = "OPENEDX_AUTHZ_SCHEMA_DIRECTORIES"
+SETTINGS_FILE_SENTINEL = "<tutor-patch>"
+SETTINGS_FILE_VERSION = "0.0.0"
 SCHEMA_FILE_SUFFIXES = (".yaml", ".yml")
 
 logger = logging.getLogger(__name__)
@@ -101,6 +108,45 @@ class DiscoveredResource:
             ) from exc
 
 
+@dataclass(frozen=True)
+class DiscoveredFileResource(DiscoveredResource):
+    """A schema file discovered via an absolute filesystem path (ADR 0030).
+
+    Unlike :class:`DiscoveredResource`, which resolves through
+    ``importlib.resources``, this variant reads directly from the filesystem.
+    Fields are populated with sentinel values: ``package`` is
+    :data:`SETTINGS_FILE_SENTINEL` and both ``module`` and ``resource_path``
+    hold the absolute path.
+    """
+
+    @classmethod
+    def from_path(cls, file_path: str) -> DiscoveredFileResource:
+        """Build a resource from an absolute filesystem path.
+
+        Sentinel values are used for ``package`` and ``module`` because the
+        file is not anchored on any Python package.
+        """
+        return cls(
+            package=SETTINGS_FILE_SENTINEL,
+            resource_path=file_path,
+            module=file_path,
+            origin=Origin.SETTINGS,
+        )
+
+    def read_bytes(self) -> bytes:
+        """Read the file directly from the filesystem via :class:`pathlib.Path`.
+
+        Raises:
+            SchemaDiscoveryError: If the file cannot be read.
+        """
+        try:
+            return Path(self.resource_path).read_bytes()
+        except OSError as exc:
+            raise SchemaDiscoveryError(
+                f"Could not read schema file {self.resource_path!r}: {exc}"
+            ) from exc
+
+
 class SchemaDiscoveryError(Exception):
     """Raised when a provider fails or a declared directory cannot be read."""
 
@@ -139,6 +185,7 @@ class SchemaDiscovery:
         found: list[DiscoveredResource] = []
         found.extend(self._discover_entry_points())
         found.extend(self._discover_settings_directories())
+        found.extend(self._discover_settings_files())
         for directory in self._passed_in_directories:
             found.extend(self._iter_directory(directory, origin=Origin.PASSED_IN))
 
@@ -184,6 +231,48 @@ class SchemaDiscovery:
             discovered.extend(self._iter_directory(directory, origin=Origin.SETTINGS))
         return discovered
 
+    def _discover_settings_files(self) -> list[DiscoveredResource]:
+        """Read ``OPENEDX_AUTHZ_SCHEMA_FILES`` from Django settings (ADR 0030).
+
+        Each item is an absolute filesystem path to a single schema file.
+        Unlike ``_discover_settings_directories``, every listed path must exist
+        and have a supported extension; a missing or misnamed file is treated
+        as a misconfiguration and raises ``SchemaDiscoveryError``.
+
+        Absent, empty, or unconfigured settings yield nothing. As with
+        ``_discover_settings_directories``, ``ImproperlyConfigured`` degrades
+        to no contribution so CI can run outside a Django process.
+        """
+        try:
+            file_paths = getattr(settings, "OPENEDX_AUTHZ_SCHEMA_FILES", None) or []
+        except ImproperlyConfigured:
+            return []
+        if not isinstance(file_paths, list):
+            raise SchemaDiscoveryError(
+                "OPENEDX_AUTHZ_SCHEMA_FILES must be a list of filesystem paths, "
+                f"got {type(file_paths).__name__!r}."
+            )
+        discovered: list[DiscoveredResource] = []
+        for file_path in file_paths:
+            if not file_path.endswith(SCHEMA_FILE_SUFFIXES):
+                raise SchemaDiscoveryError(
+                    f"Schema file {file_path!r} contributed through "
+                    "OPENEDX_AUTHZ_SCHEMA_FILES has an unsupported file extension, "
+                    f"accepted extensions: {SCHEMA_FILE_SUFFIXES}"
+                )
+
+            path = Path(file_path)
+            if not path.is_file():
+                raise SchemaDiscoveryError(
+                    f"Schema file {file_path!r} contributed through "
+                    "OPENEDX_AUTHZ_SCHEMA_FILES is not an actual file"
+                )
+
+            discovered.append(
+                DiscoveredFileResource.from_path(file_path)
+            )
+        return discovered
+
     def _iter_directory(self, directory: str, *, origin: Origin) -> list[DiscoveredResource]:
         """Resolve a directory path and return one resource per ``.yaml`` file.
 

openedx_authz-2.2.0/src/openedx_authz/engine/schema/issues.py

@@ -0,0 +1,37 @@
+"""Validation finding types shared by structural and semantic checks."""
+
+from dataclasses import dataclass
+from enum import StrEnum
+
+
+class IssueLevel(StrEnum):
+    """Severity of a :class:`ValidationIssue`.
+
+    Members:
+        ERROR: Blocks deployment.
+        WARNING: Reported only, does not block deployment.
+    """
+
+    ERROR = "error"
+    WARNING = "warning"
+
+
+@dataclass(frozen=True)
+class ValidationIssue:
+    """A single validation finding.
+
+    Attributes:
+        level: :attr:`IssueLevel.ERROR` (blocks deployment) or
+            :attr:`IssueLevel.WARNING` (reported only).
+        message: Human-readable description.
+        source_id: The contributing source, when the issue is file-specific.
+    """
+
+    level: IssueLevel
+    message: str
+    source_id: str | None = None
+
+    @property
+    def is_error(self) -> bool:
+        """Return whether this finding blocks the pipeline."""
+        return self.level == IssueLevel.ERROR

openedx_authz-2.2.0/src/openedx_authz/engine/schema/loading.py

@@ -0,0 +1,138 @@
+"""Convert parsed mappings into schema documents (the ``load`` step, ADR 0018).
+
+Each parsed document already contains its YAML mapping and source record. This
+step performs only typed structural shaping. Semantic checks belong to
+:mod:`.validation` and cross-file resolution belongs to :mod:`.compilation`.
+
+No Casbin or Django imports, so it stays unit-testable in isolation.
+"""
+
+from __future__ import annotations
+
+from openedx_authz.engine.schema.exceptions import SchemaLoadError
+from openedx_authz.engine.schema.types import (
+    ParsedSchemaDocument,
+    PermissionCategory,
+    PermissionDefinition,
+    RoleDefinition,
+    RoleExtension,
+    SchemaDocument,
+    SourceRecord,
+)
+
+
+class SchemaLoader:
+    """Turn structurally valid parsed documents into typed schema documents.
+
+    Resource reading, YAML parsing, content digests, and distribution metadata
+    belong to :class:`~openedx_authz.engine.schema.parsing.SchemaParser`. This
+    class owns only the conversion into typed definitions.
+    """
+
+    def load(self, documents: list[ParsedSchemaDocument]) -> list[SchemaDocument]:
+        """Load every parsed mapping into a :class:`SchemaDocument`.
+
+        Raises:
+            SchemaLoadError: If called with a root value that is not a mapping.
+        """
+        loaded = []
+        for document in documents:
+            if not isinstance(document.data, dict):
+                raise SchemaLoadError(f"{document.source.source_id}: schema document must be a mapping.")
+            loaded.append(self._build_document(document.data, document.source))
+        return loaded
+
+    def _build_document(self, raw: dict, source: SourceRecord) -> SchemaDocument:
+        """Map the parsed mapping's blocks into a typed SchemaDocument.
+
+        ``priority`` is a *required* field per ``authz-schema-v1.json``; a higher
+        value wins when contributions conflict (see
+        ``docs/references/authorization-schema.rst``). JSON Schema validates
+        its presence and type before this method runs. The fallback to ``0``
+        and conversion error remain defensive behavior for direct loader use.
+        """
+        try:
+            priority = int(raw.get("priority", 0))
+        except (TypeError, ValueError) as exc:
+            raise SchemaLoadError(
+                f"{source.source_id}: 'priority' must be an integer, got {raw.get('priority')!r}."
+            ) from exc
+
+        return SchemaDocument(
+            source=source,
+            priority=priority,
+            categories=[self._build_category(item, source) for item in raw.get("permission_categories", []) or []],
+            permissions=[self._build_permission(item, source) for item in raw.get("permissions", []) or []],
+            roles=[self._build_role(item, source) for item in raw.get("roles", []) or []],
+            role_extensions=[self._build_extension(item, source) for item in raw.get("role_extensions", []) or []],
+        )
+
+    @staticmethod
+    def _as_tuple(value) -> tuple[str, ...]:
+        """Coerce a YAML list (or None) into a tuple of strings."""
+        if not value:
+            return ()
+        if isinstance(value, str):
+            return (value,)
+        return tuple(str(item) for item in value)
+
+    def _build_category(self, item: dict, source: SourceRecord) -> PermissionCategory:
+        """Build a ``PermissionCategory`` from one ``permission_categories`` entry."""
+        self._require_mapping(item, "permission_categories", source)
+        return PermissionCategory(
+            id=item.get("id", ""),
+            display_name=item.get("display_name", ""),
+            description=item.get("description", ""),
+            icon=item.get("icon"),
+        )
+
+    def _build_permission(self, item: dict, source: SourceRecord) -> PermissionDefinition:
+        """Build a ``PermissionDefinition`` from one ``permissions`` entry."""
+        self._require_mapping(item, "permissions", source)
+        return PermissionDefinition(
+            namespace=item.get("namespace", ""),
+            name=item.get("name", ""),
+            display_name=item.get("display_name", ""),
+            description=item.get("description", ""),
+            category_id=item.get("category_id", ""),
+            scopes=self._as_tuple(item.get("scopes")),
+            icon=item.get("icon"),
+        )
+
+    def _build_role(self, item: dict, source: SourceRecord) -> RoleDefinition:
+        """Build a ``RoleDefinition`` from one ``roles`` entry."""
+        self._require_mapping(item, "roles", source)
+        return RoleDefinition(
+            id=item.get("id", ""),
+            display_name=item.get("display_name", ""),
+            description=item.get("description", ""),
+            scopes=self._as_tuple(item.get("scopes")),
+            permissions=self._as_tuple(item.get("permissions")),
+            icon=item.get("icon"),
+            hidden=bool(item.get("hidden", False)),
+        )
+
+    def _build_extension(self, item: dict, source: SourceRecord) -> RoleExtension:
+        """Build a ``RoleExtension`` from one ``role_extensions`` entry.
+
+        ``hidden`` is read as tri-state: absent stays ``None`` ("leave
+        unchanged"), distinct from an explicit ``False`` (ADR 0023 §1).
+        """
+        self._require_mapping(item, "role_extensions", source)
+        return RoleExtension(
+            role_id=item.get("role_id", ""),
+            add_permissions=self._as_tuple(item.get("add_permissions")),
+            remove_permissions=self._as_tuple(item.get("remove_permissions")),
+            display_name=item.get("display_name"),
+            description=item.get("description"),
+            icon=item.get("icon"),
+            hidden=item.get("hidden"),  # tri-state: None means "leave unchanged"
+        )
+
+    @staticmethod
+    def _require_mapping(item, block: str, source: SourceRecord) -> None:
+        """Raise ``SchemaLoadError`` (naming the block and source) if ``item`` is not a mapping."""
+        if not isinstance(item, dict):
+            raise SchemaLoadError(
+                f"{source.source_id}: each entry in '{block}' must be a mapping, got {type(item).__name__}."
+            )