This repository hosts versioned OpenAPI specifications and JSON schemas for the Agama installer.
Important: All specifications and schemas in this repository are generated from the main Agama codebase (either automatically for
nightlyor from maintenance branches for stable releases).This repository is a distribution mirror and does not accept direct contributions. All changes, bug fixes, or improvements to the OpenAPI definitions, JSON schemas, or documentation must be made upstream in the main Agama repository.
Specifications and schemas are organized by version or release branch:
/nightly/: Generated from the latestmasterbranch of Agama./<version>/(e.g.,16.1): Specifications and schemas corresponding to stable release branches (reflecting the latest officially released QU).
Each version directory contains:
openapi.json/openapi.yaml: The primary OpenAPI 3.1 specification, referencing extracted standalone schemas inschemas/.openapi-full.json/openapi-full.yaml: Fully resolved, monolithic OpenAPI 3.1 specification containing all component schemas inline with no external file references.schemas/: Standalone JSON schemas (Draft 2019-09) extracted for validation targets:config.schema.json: Schema for Agama autoinstallation profiles.proposal.schema.json: Schema for installation proposals.system.schema.json: Schema for system information.
Nightly specifications are automatically generated from the master branch of the Agama repository. On every push that modifies relevant files in master, a GitHub Actions workflow generates the specifications via cargo xtask openapi and automatically pushes updates to the /nightly/ directory in this repository.
Stable specifications reflect the latest officially released QU (Quarterly Update) for a given code stream. They are manually updated when the product is officially released from its respective maintenance branch:
- Check out the corresponding maintenance branch in the Agama repository.
- Generate the OpenAPI specifications and schemas:
cd rust cargo xtask openapi - Copy the whole content of
out/to the target version directory in this repository:cp -r rust/out/* /path/to/agama-openapi/<version>/
- If adding a new stable version, update
package/agama-openapi.specto include the new version directory under%files. - Commit and push the changes. The GitHub Actions workflow will automatically submit the update to OBS.
agama-openapi(built from this repository): Provides OpenAPI specifications and schemas for stable releases (e.g.16.1). Files are installed under/usr/share/agama/openapi/<version>/.agama-openapi-nightly(built from the main Agama repository): Provides nightly OpenAPI specifications and schemas generated during Agama development builds. Files are installed under/usr/share/agama/openapi/nightly/.
You can reference the JSON Schema directly in your Agama profile (JSON or YAML) for editor auto-completion and validation:
{
"$schema": "https://agama-project.github.io/openapi/nightly/schemas/config.schema.json",
"product": {
"id": "Tumbleweed"
}
}You can validate the OpenAPI specifications using tools such as openapi-spec-validator:
openapi-spec-validator nightly/openapi.json
openapi-spec-validator nightly/openapi-full.json