Catalog Schema Definition
Relevant source files
The following files were used as context for generating this wiki page:
The Catalog Schema Definition defines the structure and validation rules for catalog/packages.yaml. This file serves as the central authority for software product definitions, update sources, and installation logic within the auto-opsi-repo project.
The catalog allows the repo-builder to discover upstream releases, download installers, and package them into .opsi archives without embedding application-specific logic in the Python source code. It supports multiple metadata adapters and installation methods for Windows x64 applications.
Sources: README.md:21-23, builder/builder/catalog.py:20-22
Core Package Structure
Every entry in the catalog must be a mapping containing unique identifiers, descriptive metadata, and functional configuration. The load_catalog function validates these fields to ensure the builder can process the product.
The diagram above illustrates the top-level relationships within a single package definition.
Sources: builder/builder/catalog.py:23-45, catalog/packages.yaml:2-18
Identity and Metadata
| Field | Type | Constraint | Description |
|---|---|---|---|
id | string | Required, non-empty | Internal unique identifier for the package. |
opsi_product_id | string | Max 32 chars, lowercase regex | The unique OPSI product ID (e.g., auto-firefox). |
name | string | Required | Human-readable name of the application. |
description | string | Required | Brief description for the OPSI control file. |
enabled | boolean | Default: true | Toggles whether the builder processes this package. |
package_revision | integer | Min 1 | Manual versioning for OPSI packaging changes. |
Sources: builder/builder/catalog.py:27-33, builder/builder/catalog.py:41-45, catalog/packages.yaml:2-10
Source Configuration
The source block determines how the builder discovers new versions and retrieves installers. The type field selects a specific adapter in builder/builder/sources/adapters.py.
Source Type Requirements
The catalog validator enforces specific rules based on the source type and requires an allowed_hosts list for security pinning.
- Allowed Types:
github_release,direct_url,mozilla,videolan,documentfoundation,microsoft,vendor_json_api,winget_manifest,adoptium. - Host Validation: An explicit list of official hostnames is required. Host validation can be bypassed by setting
disable_host_validation: true.
Sources: builder/builder/catalog.py:7-18, builder/builder/catalog.py:47-51, builder/builder/sources/adapters.py:59-61
GitHub Release Schema
For type: github_release, the schema supports tracking assets and verifying checksums via the GitHub API.
| Field | Description |
|---|---|
repo | Repository path (e.g., owner/name). |
asset_regex | Regex to match the installer filename. Supports {architecture} substitution. |
checksum_asset_regex | Optional regex to find a checksum file (e.g., SHA256SUMS). |
checksum_line_regex | Optional regex to parse the checksum from the asset file. |
Sources: builder/builder/sources/adapters.py:65-72, catalog/packages.yaml:121-125
Installation and Detection Logic
The installer, detection, and uninstall blocks define the operational lifecycle of the package on a Windows client.
Detection Methods
Detection ensures that OPSI does not re-install software if the correct version is already present.
| Method | Required Fields | Description |
|---|---|---|
registry | display_name_regex | Searches HKLM Uninstall keys for a matching DisplayName. |
file_version | path | Checks the version of a specific .exe or .dll. |
msi | product_code | Checks for a specific MSI ProductCode GUID. |
custom | script | Runs a custom OPSI script snippet for version detection. |
Sources: builder/builder/catalog.py:60-70, builder/builder/opsi.py:45-48
Installer Requirements
The installer.type must be one of exe, msi, msix, or zip.
- Unattended Args:
exeandmsitypes must providesilent_argsas a list of strings. - ZIP Target:
ziptypes must specifytarget_dirto avoid polluting the system root.
Sources: builder/builder/catalog.py:52-54, builder/builder/catalog.py:71-74
The flowchart summarizes the data flow from catalog definition to the OPSI generation phase.
Sources: builder/builder/main.py:54-94, builder/builder/sources/adapters.py:126-140
Script Overrides and Templates
The schema allows for fine-grained control over OPSI script generation via templates and overrides located in catalog/overrides/.
- Control Overrides:
control.toml.j2replaces the standard metadata template. - Script Hooks: Packages can define
pre_install_opsi_script,post_install_opsi_script, and similar hooks for uninstallation. These paths must be relative to the product folder in the overrides directory. - Custom Detection: If
detection.methodiscustom, thedetection.scriptfield must point to a valid template file.
Sources: builder/builder/opsi.py:27-48, README.md:144-150
Summary
The Catalog Schema Definition provides a robust and type-safe framework for managing OPSI packages. By enforcing strict validation on OPSI IDs, host allowlists, and installer arguments, it ensures that the automated builder operates predictably. The schema balances standard behavior (like registry detection) with extensibility via custom scripts and Jinja2 templates, enabling support for a wide range of Windows applications while maintaining a single authoritative configuration file.