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.
priorityresolves conflicts on the same metadata field or the same permission (higher wins). Equal priority with disagreeing values raisesSchemaCompileErrorso 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:
EnumA family of base definitions compiled from schema documents.
attris theSchemaDocumentfield holding this family’s definitions (populated by the loader from the YAML blocks).labelis 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)
-
How a
RoleExtensionchanges a single permission on a role (ADR 0023).- ADD = 'add'
- REMOVE = 'remove'
- class openedx_authz.engine.schema.compilation.RoleMetadataField(*values)
-
Metadata fields a
RoleExtensionmay replace on a role (ADR 0023).- DESCRIPTION = 'description'
- DISPLAY_NAME = 'display_name'
- HIDDEN = 'hidden'
- ICON = 'icon'
- class openedx_authz.engine.schema.compilation.SchemaCompiler
Bases:
objectMerges validated documents into a
CompiledSchema.- compile(documents: list[SchemaDocument]) CompiledSchema
Resolve categories, permissions, roles, and extensions.
Assumes
documentsalready 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:
The
authz.schemaentry-point group. Each registered callable returns directory paths in the package-anchored format below (e.g.["openedx_authz/applets/content_libraries/schema"]).The
OPENEDX_AUTHZ_SCHEMA_DIRECTORIESDjango setting, a list of directory path strings in the same format. This lets operators and CI contribute directories without shipping a package entry point.The
OPENEDX_AUTHZ_SCHEMA_FILESDjango setting, a list of absolute filesystem paths each naming one schema file (ADR 0030). This is the route used by the Tutoropenedx-authz-schemapatch 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:
DiscoveredResourceA schema file discovered via an absolute filesystem path (ADR 0030).
Unlike
DiscoveredResource, which resolves throughimportlib.resources, this variant reads directly from the filesystem. Fields are populated with sentinel values:packageisSETTINGS_FILE_SENTINELand bothmoduleandresource_pathhold the absolute path.- classmethod from_path(file_path: str) DiscoveredFileResource
Build a resource from an absolute filesystem path.
Sentinel values are used for
packageandmodulebecause 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:
objectA single located schema file discovered inside a contributed directory.
- package
Importable top-level package used as the
importlib.resourcesanchor (e.g.openedx_authz).- Type:
- resource_path
Path to the file within that anchor (e.g.
applets/course_team_roles/schema/roles.yaml).- Type:
- 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:
- origin
Which contribution route produced this resource, as an
Originmember; 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 asresources.files(package).joinpath(resource_path). Callers (theloadstep, 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:
StrEnumDiagnostic labels for where a discovered directory was contributed from.
- Members:
ENTRY_POINT: Contributed via the
authz.schemaentry-point group. SETTINGS: Contributed via theOPENEDX_AUTHZ_SCHEMA_DIRECTORIESsetting. PASSED_IN: Passed directly intoSchemaDiscovery(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:
objectEnumerates 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
.yamlfiles, 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:
ExceptionRaised 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:
SchemaErrorApplying the rendered policy to the database is not safe to proceed.
For example, a static role slated for removal still has user assignments and
forcewas not set (ADR 0018 §6).
- exception openedx_authz.engine.schema.exceptions.SchemaCompileError
Bases:
SchemaErrorCompilation 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:
ExceptionBase class for schema pipeline errors.
- exception openedx_authz.engine.schema.exceptions.SchemaLoadError
Bases:
SchemaErrorA resource could not be parsed into a schema document.
- exception openedx_authz.engine.schema.exceptions.SchemaValidationError(issues)
Bases:
SchemaErrorValidation 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:
StrEnumSeverity 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:
objectA single validation finding.
- level
IssueLevel.ERROR(blocks deployment) orIssueLevel.WARNING(reported only).- Type:
openedx_authz.engine.schema.issues.IssueLevel
- message
Human-readable description.
- Type:
- 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
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:
objectTurn 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.
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:
objectRead discovered resources into untyped YAML values with provenance.
Each
DiscoveredResourceknows 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.metadataand hashescontentsfor 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
distributionrecords a file matchinginstalled_path.Distribution.fileslists the files the distribution installed, as anchor-relativePackagePathvalues (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’spackage/resource_path. Metadata gaps (filesisNoneor 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 arbitrarycandidates[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
resourcefrom 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:
objectRuns 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:
objectCollect JSON Schema findings for parsed documents.
- 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:
ExceptionA schema resource could not be read, parsed, or resolved for extraction.
- class openedx_authz.engine.schema.translation.TranslatableMessage(context: str, message: str)
Bases:
objectOne
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:
- message
gettext’s
msgid, the source-language (English) string to translate.- Type:
- 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
SchemaDiscoveryfinds (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.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_extensionsmay contribute their complete permission set.iconvalues, where present, are valid@openedx/paragon/iconsnames (ADR 0017 §4). The allowed set is vendored inparagon_icons(regenerate withmake paragon_icons; see ADR 0029).
- Whole-set checks (after all documents load):
Every permission
categoryreferences an existing category.Every role/extension permission references an existing permission.
A role’s
scopesare supported by each of its permissions.role_extensionstarget 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
scopesare supported by every permission it ends up with, including permissions contributed byrole_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:
objectRuns 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_extensionthat 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 enforceableprow for it (ADR 0017 §4, ADR 0023 §3).The compiled role’s permission set is the one that becomes Casbin
prows, 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.
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