openedx_authz.engine.schema package#

Subpackages#

Submodules#

openedx_authz.engine.schema.compilation module#

Resolve documents into one set of static definitions (the compile step).

Compilation (ADR 0018 §1) merges base definitions across all documents and applies role_extensions per ADR 0023:

  • Extensions resolve only after every role and permission is loaded.

  • An extension changes only the fields it includes; absent fields keep their current value; it cannot change a role ID.

  • Different fields from different contributions combine.

  • priority resolves conflicts on the same metadata field or the same permission (higher wins). Equal priority with disagreeing values raises SchemaCompileError so deployment stops before the database changes.

  • Adding a permission the role already has, or removing one it lacks, is a no-op logged as a warning.

Every resulting CompiledDefinition retains all contributing SourceRecord values, and each role-permission grant is attributed at the (role, permission) grain with its origin (base vs extension) for ADR 0025 source tracking. Output is deterministic regardless of discovery order. No Casbin/Django imports.

class openedx_authz.engine.schema.compilation.DefinitionKind(*values)

Bases: Enum

A family of base definitions compiled from schema documents.

attr is the SchemaDocument field holding this family’s definitions (populated by the loader from the YAML blocks). label is the singular noun used for this family in operator-facing error and warning messages.

CATEGORY = ('categories', 'category')
PERMISSION = ('permissions', 'permission')
ROLE = ('roles', 'role')
class openedx_authz.engine.schema.compilation.PermissionAction(*values)

Bases: str, Enum

How a RoleExtension changes a single permission on a role (ADR 0023).

ADD = 'add'
REMOVE = 'remove'
class openedx_authz.engine.schema.compilation.RoleMetadataField(*values)

Bases: str, Enum

Metadata fields a RoleExtension may replace on a role (ADR 0023).

DESCRIPTION = 'description'
DISPLAY_NAME = 'display_name'
HIDDEN = 'hidden'
ICON = 'icon'
class openedx_authz.engine.schema.compilation.SchemaCompiler

Bases: object

Merges validated documents into a CompiledSchema.

compile(documents: list[SchemaDocument]) → CompiledSchema

Resolve categories, permissions, roles, and extensions.

Assumes documents already passed validation.

Raises:

SchemaCompileError – On an unresolvable equal-priority conflict.

openedx_authz.engine.schema.discovery module#

Discover static authz schema resources (the discover step, ADR 0019).

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. ["openedx_authz/applets/content_libraries/schema"]).

  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 segment is an importable top-level package (the anchor) and the remaining forward-slash segments name a resource container within it. For example "openedx_authz/applets/content_libraries/schema" anchors on the openedx_authz package and addresses the applet’s schema subdirectory. Resolving through importlib.resources (rather than the filesystem) means discovery does not depend on virtualenv or container layout, and works even when the package is imported from a zip. If any provider raises, discovery stops and reports the failing application (ADR 0019): deployment must not proceed with an incomplete set of static definitions.

Timing: call only after Django settings are configured (from the management command or AppConfig.ready()). django.conf.settings is a lazy proxy, so importing it is inert; the setting is only read at call time, inside _discover_settings_directories. Reading before Django is configured raises ImproperlyConfigured, which is caught and treated as “no contribution” so a standalone CI schema check can run outside a Django process.

class openedx_authz.engine.schema.discovery.DiscoveredFileResource(package: str, resource_path: str, module: str, origin: Origin)

Bases: DiscoveredResource

A schema file discovered via an absolute filesystem path (ADR 0030).

Unlike DiscoveredResource, which resolves through importlib.resources, this variant reads directly from the filesystem. Fields are populated with sentinel values: package is SETTINGS_FILE_SENTINEL and both module and resource_path hold the absolute path.

classmethod from_path(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.

read_bytes() → bytes

Read the file directly from the filesystem via pathlib.Path.

Raises:

SchemaDiscoveryError – If the file cannot be read.

class openedx_authz.engine.schema.discovery.DiscoveredResource(package: str, resource_path: str, module: str, origin: Origin)

Bases: object

A single located schema file discovered inside a contributed directory.

package

Importable top-level package used as the importlib.resources anchor (e.g. openedx_authz).

Type:

str

resource_path

Path to the file within that anchor (e.g. applets/course_team_roles/schema/roles.yaml).

Type:

str

module

Dotted path of the owning directory, used as the source-record module and provenance identity (e.g. openedx_authz.applets.course_team_roles.schema).

Type:

str

origin

Which contribution route produced this resource, as an Origin member; diagnostics only.

Type:

openedx_authz.engine.schema.discovery.Origin

module: str
origin: Origin
package: str
read_bytes() → bytes

Read this resource’s bytes via importlib.resources.

Encapsulates the anchoring convention shared with directory discovery: a resource is a (package, resource_path) pair resolved as resources.files(package).joinpath(resource_path). Callers (the load step, ADR 0018) decide when to read; this keeps the how beside where the resource is produced.

Raises:

SchemaDiscoveryError – If the resource cannot be located or read.

resource_path: str
class openedx_authz.engine.schema.discovery.Origin(*values)

Bases: StrEnum

Diagnostic labels for where a discovered directory was contributed from.

Members:

ENTRY_POINT: Contributed via the authz.schema entry-point group. SETTINGS: Contributed via the OPENEDX_AUTHZ_SCHEMA_DIRECTORIES setting. PASSED_IN: Passed directly into SchemaDiscovery (CI/local mode).

ENTRY_POINT = 'entry_point'
PASSED_IN = 'passed_in'
SETTINGS = 'settings'
class openedx_authz.engine.schema.discovery.SchemaDiscovery(*, passed_in_directories: list[str] | None = None)

Bases: object

Enumerates registered schema directories into discovered files.

discover() → list[DiscoveredResource]

Return every discovered schema file in a deterministic order.

Expands entry-point directories, settings directories, and passed-in directories into individual .yaml files, then de-duplicates and sorts. Order is normalized here because discovery order may vary across environments (ADR 0019); priority — not discovery order — drives conflict resolution later.

Sorting default: results are ordered by (package, resource_path) ascending, so the same set of directories always yields the same list regardless of the order sources were discovered in.

Raises:

SchemaDiscoveryError – If a provider callable raises or a declared directory cannot be located/read.

exception openedx_authz.engine.schema.discovery.SchemaDiscoveryError

Bases: Exception

Raised when a provider fails or a declared directory cannot be read.

openedx_authz.engine.schema.exceptions module#

Exceptions for the authz schema pipeline.

exception openedx_authz.engine.schema.exceptions.SchemaApplyError

Bases: SchemaError

Applying the rendered policy to the database is not safe to proceed.

For example, a static role slated for removal still has user assignments and force was not set (ADR 0018 §6).

exception openedx_authz.engine.schema.exceptions.SchemaCompileError

Bases: SchemaError

Compilation could not resolve the definitions.

For example, an unresolvable role_extension conflict at equal priority (ADR 0023).

exception openedx_authz.engine.schema.exceptions.SchemaError

Bases: Exception

Base class for schema pipeline errors.

exception openedx_authz.engine.schema.exceptions.SchemaLoadError

Bases: SchemaError

A resource could not be parsed into a schema document.

exception openedx_authz.engine.schema.exceptions.SchemaValidationError(issues)

Bases: SchemaError

Validation found error-level issues; deployment must stop.

Carries the collected issues so the caller can report them all at once rather than failing on the first problem.

openedx_authz.engine.schema.issues module#

Validation finding types shared by structural and semantic checks.

class openedx_authz.engine.schema.issues.IssueLevel(*values)

Bases: StrEnum

Severity of a ValidationIssue.

Members:

ERROR: Blocks deployment. WARNING: Reported only, does not block deployment.

ERROR = 'error'
WARNING = 'warning'
class openedx_authz.engine.schema.issues.ValidationIssue(level: IssueLevel, message: str, source_id: str | None = None)

Bases: object

A single validation finding.

level

IssueLevel.ERROR (blocks deployment) or IssueLevel.WARNING (reported only).

Type:

openedx_authz.engine.schema.issues.IssueLevel

message

Human-readable description.

Type:

str

source_id

The contributing source, when the issue is file-specific.

Type:

str | None

property is_error: bool

Return whether this finding blocks the pipeline.

level: IssueLevel
message: str
source_id: str | None = None

openedx_authz.engine.schema.loading module#

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 validation and cross-file resolution belongs to compilation.

No Casbin or Django imports, so it stays unit-testable in isolation.

class openedx_authz.engine.schema.loading.SchemaLoader

Bases: object

Turn structurally valid parsed documents into typed schema documents.

Resource reading, YAML parsing, content digests, and distribution metadata belong to SchemaParser. This class owns only the conversion into typed definitions.

load(documents: list[ParsedSchemaDocument]) → list[SchemaDocument]

Load every parsed mapping into a SchemaDocument.

Raises:

SchemaLoadError – If called with a root value that is not a mapping.

openedx_authz.engine.schema.paragon_icons module#

Vendored allow-list of valid @openedx/paragon/icons names.

GENERATED FILE – do not edit by hand. Regenerate with:

make paragon_icons

The names are the component exports of @openedx/paragon/icons at the pinned version below, used by openedx_authz.engine.schema.validation to reject schema icon values that are not real Paragon icons (ADR 0017 §4).

Source: https://unpkg.com/@openedx/paragon@23.21.3/icons/es5/index.js Paragon version: 23.21.3 Icon count: 2317

openedx_authz.engine.schema.parsing module#

Read discovered resources into parsed documents (the parse step, ADR 0018).

Parses each YAML schema resource without imposing authorization-schema structure, attaching its SourceRecord with a content digest computed from the exact bytes read. JSON Schema validation owns structural requirements, typed shaping belongs to loading, and semantic checks belong to validation.

No Casbin or Django imports, so parsing stays unit-testable in isolation.

class openedx_authz.engine.schema.parsing.SchemaParser

Bases: object

Read discovered resources into untyped YAML values with provenance.

Each 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.

build_source_record(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_ambiguity_warned: set[tuple[str, str, str]] = {}

Tracks warned (package, resource_path, selected) combinations to deduplicate logs.

static 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/applets/course_team_roles/schema/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.

parse(resources: list[DiscoveredResource]) → list[ParsedSchemaDocument]

Parse every resource without imposing authorization-schema structure.

static parse_yamls(contents: bytes, resource: DiscoveredResource) → list[object]

Parse YAML bytes as a multi-document stream, skipping empty documents, and preserve the resulting root value.

classmethod resolve_distribution(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.

classmethod select_owning_distribution(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.

openedx_authz.engine.schema.pipeline module#

End-to-end orchestration of the authz schema lifecycle (ADR 0018).

SchemaPipeline wires the steps together:

discover -> parse -> validate structure -> load -> validate semantics -> compile -> render -> (plan) -> apply

The Casbin-free steps (discover..compile) live in openedx_authz.engine.schema; render/apply live in openedx_authz.engine.renderer. This orchestrator is the single entry point used by the deployment management command and by tests.

Deployment runs discover-through-apply before the application serves traffic (ADR 0018 §2). CI/local runs may stop after plan for a dry run, or pass explicit resources.

class openedx_authz.engine.schema.pipeline.SchemaPipeline(*, 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, renderer: PolicyRenderer | None = None, applier: SchemaApplier | None = None)

Bases: object

Runs the schema lifecycle from discovery through apply.

Components are injected for testability; each defaults to its standard implementation.

apply(*, force: bool = False) → ApplyResult

Run the full lifecycle and persist the result transactionally.

Parameters:

force – Allow removal of roles that still have assignments (ADR 0018).

compile() → CompiledSchema

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 checked after they are applied (ADR 0017 §4).

Raises:
  • SchemaValidationError – If either validation pass finds error-level issues.

  • SchemaCompileError – On an unresolvable conflict.

plan() → ChangePlan

Run through render and produce the change report without writing.

Used for dry-run / CI review (ADR 0018 §6).

openedx_authz.engine.schema.snapshot module#

Utilities for rendering a compiled schema as a readable snapshot.

openedx_authz.engine.schema.snapshot.group_role_permissions(role_id: str, permissions: tuple[str, ...], relationships: dict[tuple[str, str], list[RelationshipSource]]) → dict[str, list[str]]

Group a role’s permissions by every applet that contributed each relationship.

openedx_authz.engine.schema.snapshot.render_category(compiled_category: CompiledDefinition) → dict[str, object]

Render one compiled permission category with its owning applet.

openedx_authz.engine.schema.snapshot.render_permission(compiled_permission: CompiledDefinition) → dict[str, object]

Render one compiled permission with its owning applet.

openedx_authz.engine.schema.snapshot.render_role(role_id: str, compiled_role: CompiledDefinition, relationships: dict[tuple[str, str], list[RelationshipSource]]) → dict[str, object]

Render one compiled role for the readable snapshot.

openedx_authz.engine.schema.snapshot.snapshot_data(compiled: CompiledSchema) → dict[str, dict[str, dict[str, object]]]

Return the compiled schema as a readable mapping of roles, permissions, and categories.

Each role lists its permissions grouped by the applet that adds them, so the snapshot shows how base definitions and role extensions compose each role.

openedx_authz.engine.schema.snapshot.source_applet_name(source: SourceRecord) → str

Return the applet that owns a schema source, or its module when no applet owns it.

openedx_authz.engine.schema.syntax module#

Validate parsed schema values against the configured JSON Schema.

The schema owns supported schema_version values, required fields, identifier and permission-reference formats, scope formats, collection shapes, value types, and Paragon icon-name format. Semantic relationship and icon membership checks remain in validation.

class openedx_authz.engine.schema.syntax.SchemaSyntaxValidator

Bases: object

Collect JSON Schema findings for parsed documents.

validate(documents: list[ParsedSchemaDocument]) → list[ValidationIssue]

Return every structural error from every parsed document.

openedx_authz.engine.schema.syntax.configured_schema_resource() → str

Return the configured JSON Schema resource, including outside Django.

openedx_authz.engine.schema.syntax.document_validator(schema_resource: str) → Draft202012Validator

Load an authorization validator from a package resource.

openedx_authz.engine.schema.translation module#

Extract translatable strings from the static authz schema (ADR 0020).

The authz schema’s display_name and description fields are source-language text that end users see through APIs and frontend clients, so they need to go through the Open edX translation process (OEP-58). Standard extraction tools only scan Python and JavaScript source, so they can’t find strings written in YAML.

This module reads every discovered schema resource directly with yaml.safe_load, independent of the schema load/validate/compile pipeline: it only needs the raw display_name/description fields, not the richer typed documents those steps build, so it stays usable (and testable) against ad hoc or malformed schema directories, not just a fully valid one. It does, however, resolve conflicts between files the same way engine.schema.compilation does: by each document’s priority (higher wins; identical content merges; a disagreement at equal priority is an error), so the generated catalog reflects the same winner the compiled schema would use at runtime. Re-deriving that one rule here (rather than depending on the loader/compiler) is what keeps this module usable before, or independently of, that pipeline.

It emits a generated Python module containing one pgettext() call per translatable field, which i18n_tool extract (a thin wrapper around Django’s makemessages) then picks up like any other source file. pgettext is used instead of plain gettext because ADR 0020 requires a permission’s display name and description to remain separate translation messages even when they contain the same English text; a plain gettext call would merge identical msgids into one catalog entry. The first pgettext() argument is gettext’s msgctxt: it carries the field’s stable identifier, so two different roles that happen to share a one-word name like “Admin” stay separate messages too.

This generated module is never imported or executed: its only purpose is to be valid Python source for makemessages to scan. At runtime, the schema catalog API looks up a field’s source-language value directly with the same pgettext(context, value) pair used here, so the generated calls must stay in sync with however that lookup builds its context string.

exception openedx_authz.engine.schema.translation.SchemaTranslationExtractionError

Bases: Exception

A schema resource could not be read, parsed, or resolved for extraction.

class openedx_authz.engine.schema.translation.TranslatableMessage(context: str, message: str)

Bases: object

One pgettext(context, message) pair extracted from the schema.

context

gettext’s msgctxt. Disambiguates otherwise-identical messages, formatted as "{field_kind}.{field_name}:{stable_id}", e.g. "permission.display_name:courses.view_course".

Type:

str

message

gettext’s msgid, the source-language (English) string to translate.

Type:

str

context: str
message: str
openedx_authz.engine.schema.translation.extract_messages(resources: list[DiscoveredResource] | None = None) → list[TranslatableMessage]

Extract every translatable schema string from the given (or discovered) resources.

Parameters:

resources – Resources to extract from. Defaults to everything SchemaDiscovery finds (every registered schema directory), which is what the management command uses.

Returns:

Deduplicated messages, sorted by context, so the generated file’s diffs are stable across runs regardless of discovery order.

Raises:

SchemaTranslationExtractionError – A resource’s bytes couldn’t be read, it wasn’t valid YAML, a section wasn’t shaped as the schema requires, an entry was missing its identifying field, a translatable string collided with gettext’s own context separator, or two documents disagreed on the same field at equal priority. A translation build must fail loudly here (ADR 0020) rather than silently produce a catalog that doesn’t match what the compiled schema would serve.

openedx_authz.engine.schema.translation.render_module(messages: list[TranslatableMessage]) → str

Render the extracted messages as a generated Python module’s source text.

openedx_authz.engine.schema.validation module#

Validate schema documents individually and as a whole (the validate step).

Rules come from ADR 0017 §4 and the field reference:

Per-document checks:
  • Roles with no base permissions are accepted with a warning because role_extensions may contribute their complete permission set.

  • icon values, where present, are valid @openedx/paragon/icons names (ADR 0017 §4). The allowed set is vendored in paragon_icons (regenerate with make paragon_icons; see ADR 0029).

Whole-set checks (after all documents load):
  • Every permission category references an existing category.

  • Every role/extension permission references an existing permission.

  • A role’s scopes are supported by each of its permissions.

  • role_extensions target an existing role (ADR 0023).

  • Conflicting duplicate base definitions fail; identical duplicates warn.

Post-compile checks (after extensions and priority are resolved):
  • A role’s scopes are supported by every permission it ends up with, including permissions contributed by role_extensions.

  • The resolved permissions and categories still exist.

Validation collects issues rather than raising on the first problem, so the deployment report can list every error and warning at once. No Casbin imports.

class openedx_authz.engine.schema.validation.SchemaValidator

Bases: object

Runs per-document and whole-set validation.

validate(documents: list[SchemaDocument]) → list[ValidationIssue]

Run per-document then whole-set validation, returning all issues.

validate_compiled(schema: CompiledSchema) → list[ValidationIssue]

Re-check the resolved schema after extensions and priority are applied.

Document-level validation only sees base declarations, so a role_extension that adds a permission is checked for existence but never for scope compatibility. Without this pass an extension can grant a permission in a scope the permission does not support, and the renderer still emits an enforceable p row for it (ADR 0017 §4, ADR 0023 §3).

The compiled role’s permission set is the one that becomes Casbin p rows, so it is the set that has to satisfy the scope rule.

validate_document(document: SchemaDocument) → list[ValidationIssue]

Per-file checks that need no cross-file context.

validate_set(documents: list[SchemaDocument]) → list[ValidationIssue]

Whole-set checks across all loaded documents.

Module contents#

Authorization schema pipeline.

Turns on-disk .yaml schema resources into a validated, compiled set of static definitions, following the lifecycle defined in the authz ADRs:

discover -> load -> validate -> compile (this package, Casbin-free) render -> apply (openedx_authz.engine.renderer) consume (existing enforcer + APIs)

References

  • ADR 0017 - static authorization schema (format)

  • ADR 0018 - authorization schema lifecycle (vocabulary + semantics)

  • ADR 0019 - authorization schema discovery (entry points + resources)

  • ADR 0023 - extend static roles (role_extensions merge rules)

  • docs/references/authorization-schema.rst - field-level reference