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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openedx-authz
-Version: 2.0.0
+Version: 2.1.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.1.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.1.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.1.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.1.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.1.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.1.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.1.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.1.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.1.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__}."
+            )

openedx_authz-2.1.0/src/openedx_authz/engine/schema/parsing.py

@@ -0,0 +1,169 @@
+"""Read discovered resources into parsed documents (the ``parse`` step, ADR 0018).
+
+Parses each YAML schema resource without imposing authorization-schema
+structure, attaching its :class:`SourceRecord` with a content digest computed
+from the exact bytes read. JSON Schema validation owns structural requirements,
+typed shaping belongs to :mod:`.loading`, and semantic checks belong to
+:mod:`.validation`.
+
+No Casbin or Django imports, so parsing stays unit-testable in isolation.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+from importlib import metadata
+
+import yaml
+
+from openedx_authz.engine.schema.discovery import DiscoveredResource
+from openedx_authz.engine.schema.exceptions import SchemaLoadError
+from openedx_authz.engine.schema.types import ParsedSchemaDocument, SourceRecord
+
+logger = logging.getLogger(__name__)
+
+UNKNOWN_DISTRIBUTION = "unknown"
+
+
+class SchemaParser:
+    """Read discovered resources into untyped YAML values with provenance.
+
+    Each :class:`DiscoveredResource` knows how to read itself, so the parser
+    controls when files are read and computes the content digest from the exact
+    bytes passed to the YAML parser.
+    """
+
+    distribution_ambiguity_warned: set[tuple[str, str, str]] = set()
+    """Tracks warned (package, resource_path, selected) combinations to deduplicate logs."""
+
+    def parse(self, resources: list[DiscoveredResource]) -> list[ParsedSchemaDocument]:
+        """Parse every resource without imposing authorization-schema structure."""
+        documents = []
+        for resource in resources:
+            contents = resource.read_bytes()
+            data = self.parse_yaml(contents, resource)
+            schema_version = str(data.get("schema_version", "")) if isinstance(data, dict) else ""
+            source = self.build_source_record(resource, contents, schema_version)
+            documents.append(ParsedSchemaDocument(source=source, data=data))
+        return documents
+
+    @staticmethod
+    def parse_yaml(contents: bytes, resource: DiscoveredResource) -> object:
+        """Parse YAML bytes and preserve the resulting root value."""
+        try:
+            return yaml.safe_load(contents)
+        except yaml.YAMLError as exc:
+            raise SchemaLoadError(f"Invalid YAML in {resource.package}:{resource.resource_path}: {exc}") from exc
+
+    def build_source_record(self, resource: DiscoveredResource, contents: bytes, schema_version: str) -> SourceRecord:
+        """Assemble packaging metadata and a digest into a SourceRecord.
+
+        Resolves the installed distribution name/version that owns the resource
+        package via ``importlib.metadata`` and hashes ``contents`` for the
+        digest. Falls back to ``"unknown"`` when the package is not tied to an
+        installed distribution (e.g. operator-supplied settings resources).
+        """
+        distribution, version = self.resolve_distribution(resource)
+        content_digest = hashlib.sha256(contents).hexdigest()
+        return SourceRecord(
+            distribution=distribution,
+            distribution_version=version,
+            module=resource.module,
+            resource_path=resource.resource_path,
+            schema_version=schema_version,
+            content_digest=content_digest,
+        )
+
+    @classmethod
+    def resolve_distribution(cls, resource: DiscoveredResource) -> tuple[str, str]:
+        """Map a discovered resource to its providing distribution name and version.
+
+        A top-level import package can be provided by more than one installed
+        distribution (namespace packages, overlapping/legacy installs), so
+        ``packages_distributions()`` returns a *list* of candidate names. The
+        same source must resolve to the same distribution under every deployment
+        layout (ADR 0019 §2), so an arbitrary ``candidates[0]`` is not good
+        enough: when several distributions claim the top-level package we pick
+        the one that actually ships this resource's file, and only fall back to
+        a deterministic (sorted) choice when no single owner can be identified.
+        """
+        top_level = resource.package.split(".", 1)[0]
+        try:
+            mapping = metadata.packages_distributions()
+        except Exception:  # pylint: disable=broad-exception-caught  # noqa: BLE001 - defensive; metadata quirks across envs
+            mapping = {}
+        # ``packages_distributions()`` can list the same distribution more than
+        # once for one top-level package (observed with editable installs and
+        # overlapping metadata). Those are not competing owners, so collapse to
+        # the distinct names before resolving; otherwise a lone real owner that
+        # happens to be listed twice looks "ambiguous" and the fallback path
+        # warns on every resource for a non-problem.
+        candidates = sorted(set(mapping.get(top_level) or []))
+        if not candidates:
+            return top_level, UNKNOWN_DISTRIBUTION
+
+        distribution = cls.select_owning_distribution(candidates, resource)
+        try:
+            return distribution, metadata.version(distribution)
+        except metadata.PackageNotFoundError:
+            return distribution, UNKNOWN_DISTRIBUTION
+
+    @classmethod
+    def select_owning_distribution(cls, candidates: list[str], resource: DiscoveredResource) -> str:
+        """Choose the distribution that ships ``resource`` from the candidate list.
+
+        With a single candidate there is nothing to disambiguate. With several,
+        we match each distribution's recorded file list against the resource's
+        installed path (``package/resource_path``) and return the one that owns
+        it. If exactly zero or more than one distribution claims the file (or the
+        file lists are unavailable), we cannot know the true owner, so we return
+        the first candidate in sorted order, a stable choice across environments,
+        and log the ambiguity once per distinct (package, resource_path, selected)
+        combination.
+        """
+        if len(candidates) == 1:
+            return candidates[0]
+
+        installed_path = f"{resource.package}/{resource.resource_path}"
+        owners = [name for name in candidates if cls.distribution_ships(name, installed_path)]
+        if len(owners) == 1:
+            return owners[0]
+
+        fallback = sorted(candidates)[0]
+        # Deduplicate warnings by tracking (package, resource_path, selected) combinations.
+        warn_key = (resource.package, resource.resource_path, fallback)
+        if warn_key not in cls.distribution_ambiguity_warned:
+            cls.distribution_ambiguity_warned.add(warn_key)
+            logger.info(
+                "Schema resource for package '%s' is claimed by multiple distributions %s; "
+                "deterministically selected '%s'.",
+                resource.package,
+                sorted(candidates),
+                fallback,
+                extra={
+                    "package": resource.package,
+                    "resource_path": resource.resource_path,
+                    "candidates": sorted(candidates),
+                    "matched_owners": sorted(owners),
+                    "selected": fallback,
+                },
+            )
+        return fallback
+
+    @staticmethod
+    def distribution_ships(distribution: str, installed_path: str) -> bool:
+        """Return whether ``distribution`` records a file matching ``installed_path``.
+
+        ``Distribution.files`` lists the files the distribution installed, as
+        anchor-relative ``PackagePath`` values (e.g.
+        ``openedx_authz/authz/schema/course_roles.yaml``). A resource belongs to
+        the distribution when one of those paths ends with the resource's
+        ``package/resource_path``. Metadata gaps (``files`` is ``None`` or the
+        distribution is missing) mean "cannot confirm ownership", not an error.
+        """
+        try:
+            files = metadata.distribution(distribution).files or []
+        except metadata.PackageNotFoundError:
+            return False
+        return any(str(path).endswith(installed_path) for path in files)

{openedx_authz-2.0.0 → openedx_authz-2.1.0}/src/openedx_authz/engine/schema/pipeline.py

@@ -2,7 +2,7 @@
 
 :class:`SchemaPipeline` wires the steps together:
 
-    discover -> load -> validate -> compile -> render -> (plan) -> apply
+    discover -> parse -> validate structure -> load -> validate semantics -> compile -> render -> (plan) -> apply
 
 The Casbin-free steps (discover..compile) live in :mod:`openedx_authz.engine.schema`;
 render/apply live in :mod:`openedx_authz.engine.renderer`. This orchestrator is
@@ -26,9 +26,12 @@ from openedx_authz.engine.renderer import (
 from openedx_authz.engine.schema.compilation import SchemaCompiler
 from openedx_authz.engine.schema.discovery import SchemaDiscovery
 from openedx_authz.engine.schema.exceptions import SchemaValidationError
+from openedx_authz.engine.schema.issues import ValidationIssue
 from openedx_authz.engine.schema.loading import SchemaLoader
+from openedx_authz.engine.schema.parsing import SchemaParser
+from openedx_authz.engine.schema.syntax import SchemaSyntaxValidator
 from openedx_authz.engine.schema.types import CompiledSchema
-from openedx_authz.engine.schema.validation import SchemaValidator, ValidationIssue
+from openedx_authz.engine.schema.validation import SchemaValidator
 
 logger = logging.getLogger(__name__)
 
@@ -44,6 +47,8 @@ class SchemaPipeline:
         self,
         *,
         discovery: SchemaDiscovery | None = None,
+        parser: SchemaParser | None = None,
+        syntax_validator: SchemaSyntaxValidator | None = None,
         loader: SchemaLoader | None = None,
         validator: SchemaValidator | None = None,
         compiler: SchemaCompiler | None = None,
@@ -51,6 +56,8 @@ class SchemaPipeline:
         applier: SchemaApplier | None = None,
     ):
         self._discovery = discovery or SchemaDiscovery()
+        self._parser = parser or SchemaParser()
+        self._syntax_validator = syntax_validator or SchemaSyntaxValidator()
         self._loader = loader or SchemaLoader()
         self._validator = validator or SchemaValidator()
         self._compiler = compiler or SchemaCompiler()
@@ -58,7 +65,7 @@ class SchemaPipeline:
         self._applier = applier or SchemaApplier()
 
     def compile(self) -> CompiledSchema:
-        """Run discover -> load -> validate -> compile and return the result.
+        """Run discover -> parse -> validate syntax -> load -> validate semantics -> compile and return the result.
 
         Validation gates twice: once on the loaded documents, then again on the
         compiled schema, because extensions and priority resolution can only be
@@ -70,7 +77,9 @@ class SchemaPipeline:
             SchemaCompileError: On an unresolvable conflict.
         """
         resources = self._discovery.discover()
-        documents = self._loader.load(resources)
+        parsed_documents = self._parser.parse(resources)
+        self._gate(self._syntax_validator.validate(parsed_documents))
+        documents = self._loader.load(parsed_documents)
 
         self._gate(self._validator.validate(documents))
         schema = self._compiler.compile(documents)
@@ -87,7 +96,7 @@ class SchemaPipeline:
         for issue in issues:
             log = logger.error if issue.is_error else logger.warning
             log("authz schema %s: %s [%s]", issue.level, issue.message, issue.source_id or "-")
-        if self._validator.has_errors(issues):
+        if any(issue.is_error for issue in issues):
             raise SchemaValidationError([i for i in issues if i.is_error])
 
     def plan(self) -> ChangePlan: