Software Catalog (linxira-catalog)
Why it exists
The installer, Package Center, Component Manager and Welcome all need to know which software exists, how it is categorised, what is selected by default and whether it can install offline. With a separate list per surface, IDs, defaults and review states drift.
linxira-catalog is the single reviewed, versioned source of software component metadata.
It describes software and the selection model; it never performs a package transaction.
Responsibilities
It owns:
catalog-v3.json: the graph ofdesktops[],applications[],components[],bundles[],operations[]andcategories[].schema/*.schema.json: JSON Schema Draft 2020-12 contracts, validated in the build.- Stable leaf IDs shared by the installer, managers, plans, receipts and CLI handoffs.
- Offline policy:
included,online-onlyanddefer-with-consent, so every install surface shows the same badge. catalog-v2.jsonas a compatibility input for existing consumers. v3 does not replace the v2profiles[]model.
It does not own:
- Planning, confirmation, execution or receipts — that is Components.
- A user-facing command. The package installs data and schemas, not a CLI.
- Executable command strings.
operations[]contains fixed, controlled operation IDs only. - Any downstream repository. The installer and the managers read the fixed paths and never write the catalog back.
Entry contract
Every leaf (desktop, application, component, bundle) declares enough for a downstream surface to display it and select it safely:
| Field | Purpose |
|---|---|
id / kind / name |
Stable ID, entry kind, and the zh_CN and en display names |
primaryCategory |
The single category it belongs to; the category declares its own selection.mode (multi, exclusive, bounded or preset) |
provider / source / artifact |
Which ecosystem provides it (pacman, aur, flatpak, conda, pip, builtin), which source it comes from, and which package identifiers it installs |
license |
License classification, SPDX identifier, redistributability, and whether the user must accept it |
review |
Review status and date |
availability |
available, review-channel or unavailable, the offlinePolicy, and the default or optional-review channel |
presentation |
Recommended flag, default-selected flag, order, and installer visibility |
The schema is strict: top-level additionalProperties is false, so any field outside the contract fails validation. catalogVersion is fixed at 3, and release has the form YYYY.MM.
Review contract
review.statushas exactly four values:reviewed,vm-test-pending,source-review-pendingandlegal-review-pending. Only areviewedleaf may be default-selected.- Installer-visible leaves additionally require
review.status == "reviewed"; candidates still in review stay in thereview-channeland are never default-selected. - External ecosystems (AUR, Conda, proprietary software) are disabled by default and need an explicit user opt-in.
conda-forgeandbiocondaare explicit sources that the base system never enables. operations[]holds fixed, controlled operation IDs only (reviewedorvm-test-pending), never a shell string.- A category-root bundle must mirror its category's children in order, all as optional references; nested bundles must form a DAG.
How to use
Users do not call this repository directly. The linxira-catalog package installs:
/usr/share/linxira/catalog/catalog-v3.json
/usr/share/linxira/catalog/catalog-v3.schema.json
Consumers read those fixed paths and present them in their own UI:
| Consumer | Purpose |
|---|---|
| Installer | Desktop, application and component selection during installation |
| Package Center | Installed-state and software presentation |
| Component Manager | Runtime, tool and capability state |
| Completion Agent | First-online completion plan |
| Components | Transaction plans built from leaf IDs |
Maintainer validation:
python -m unittest discover -s tests -v
Validation covers schemas, category-root ID pairs and all global IDs, references,
primaryCategory ownership, bundle surfaces, nested-bundle acyclicity, duplicate members,
provider/source boundaries, review-channel policy, offline policy and selection modes.
When root is required
Never. The catalog is read-only data; writes happen only during repository development and packaging.
Known limitations
- The installed package ships v3 data and schema only. v2 remains in the repository for
older consumers; do not reuse the v2
profiles[]capability model in v3. - Selection and receipts are keyed by leaf ID, not by tree path; removing a leaf or changing a stable ID affects every downstream consumer.
- The catalog lists package identifiers and metadata, not installation commands. Being in the catalog does not mean the software is installed.
Design notes
See linxira-catalog. How transactions
consume leaf IDs is described in Components.