0029: Maintaining the Vendored Paragon Icon Allow-List#
Status#
Draft
Context#
ADR 0017 §4 requires schema validation to reject icon values that are not
valid names exported by @openedx/paragon/icons. Categories, permissions,
roles, and role extensions each carry an optional Paragon icon name (for example
BookOpen or RemoveRedEye), and those names are used by frontends to
render the schema.
openedx-authz is a Python backend with no Node or Paragon dependency, so the
JavaScript icon package cannot be imported at validation time. There is no
Python-side source of truth for the set of valid icon names, and the set changes
whenever Paragon adds, renames, or removes an icon.
Paragon publishes its icons as component exports from @openedx/paragon/icons.
The built export barrel (icons/es5/index.js in a published release) lists
every icon as export { default as <IconName> } from "./<file>";, which is a
stable, machine-readable source for the name set.
Decision#
We vendor the icon-name allow-list as a generated Python module,
openedx_authz/engine/schema/paragon_icons.py, exposing
PARAGON_ICON_NAMES: frozenset[str]. The schema validator imports this
frozenset and rejects any icon value that is not a member (ADR 0017 §4).
The list is generated by scripts/generate_paragon_icons.py, run via
make paragon_icons. The script fetches the icon export barrel for a pinned
Paragon version from the public npm CDN, parses the exported names, and writes
the vendored module. The generated file is committed to the repository so that
validation is deterministic and needs no network access at runtime.
Pinned version. The generator pins the Paragon version to match the
@openedx/paragon major that frontend-app-admin-console declares on its
master branch (currently ^23, generated from 23.21.3). That MFE is
the primary consumer that renders these icons, so aligning the allow-list with
the version it ships keeps validation honest: an icon that validates here is one
the console can actually render.
Update process. Regenerate the list whenever
frontend-app-admin-console changes its @openedx/paragon version:
Update
PARAGON_VERSIONinscripts/generate_paragon_icons.pyto the new pinned release.Run
make paragon_iconsto rewriteparagon_icons.py.Commit the regenerated file together with the version bump.
make paragon_icons_check regenerates the list into memory and fails if the
committed file is stale; wire it into CI to catch a forgotten refresh after a
version bump.
Deprecation. When Paragon renames or removes an icon, the change lands in the
allow-list at the next regeneration. Any schema icon value that no longer
exists then fails validation as an error, following the same deprecation path as
other consumers of @openedx/paragon/icons (ADR 0017 §4).
Consequences#
Icon validation is deterministic, offline, and requires no Node dependency in the Python backend.
The allow-list can drift from the latest Paragon release between refreshes. This is intentional: it tracks the version the console consumes, not the newest published icons, and the
paragon_icons_checktarget surfaces staleness.Bumping the console’s Paragon version is now a two-repo change: someone must refresh the vendored list here so newly available icons validate and removed icons are rejected.
paragon_icons.pyis a generated artifact; it must not be edited by hand.