feat: add typespec schemas for modules (#233)

* feat: add typespec for bling and akmods for testing

* chore: temporarily change module source to dev branch

* feat: add missing module typespecs from blue-build/schema

* feat: add schemas for default-flatpaks module

* chore: annotate some parameters as optional

* fix: typo in default-flatpaks schema

* feat: add schema for files module

* feat: add script module schema

* feat: add signing module schema

* docs: add module.yml docs etc.

* fix(default-flatpaks): don't capitalize string in typespec

* feat: add schemas for gnome-extensions

* fix(files): properly declare string: string record type

* chore: add tsp for gschema-overrides

* chore: tsp for systemd module

* chore: add link to systemd tsp to module.yml

* chore: add tsp for yafti module

* feat: add docstrings for files module

* feat: add tsp for chezmoi module

* feat: docstrings for akmods tsp

* feat: docstrings for bling tsp

* feat: docstrings for default flatpaks tsp

* fix: link to files module docs page in files module tsp

* feat: docstrings for fonts module tsp

* feat: add docstrings for gnome extensions tsp

* feat: docstrings for gschema overrides tsp

* feat: docstrings for rpm ostree tsp

* feat: docstrings for script tsp

* feat: docstrings for signing module

* feat: docstrings for systemd tsp

* feat: docstrings for yafti module

* fix: typo in files tsp

* feat: typespec for brew module

* chore: update rpm ostree tsp for keys: prop

* fix: use typespec to declare default values

* fix: errors from previous commit

* docs: add typespec instructions

* docs: chore: add typespec docs link for docs syntax

* chore: switch to semicolon for ending property definitions

* docs: fix: typo inlude -> include

* feat: tsp for justfiles module

* chore: change links to reference main branch

---------

Co-authored-by: fiftydinar <65243233+fiftydinar@users.noreply.github.com>

README.md

@@ -24,10 +24,12 @@ These are general guidelines for writing official bash modules and their documen
 - If you want to insert another regular string as a suffix or prefix to the `"${variable_name}"`, you should do that in this format: `"prefix-${variable_name}-suffix"`
 - Use `set -euo pipefail` at the start of the script, to ensure that module will fail the image build if error is caught.
      -  You can also use `set -euxo pipefail` during debugging, where each executed command is printed. This should not be used in a published module. 
+  
+Using [Shellcheck](https://www.shellcheck.net/) in your editor is recommended.
 
 ### Documentation
 
-Every public module should have a `module.yml` ([reference](https://blue-build.org/reference/module/#moduleyml)) file for metadata and a `README.md` file for an in-depth description. 
+Every public module should have a `module.yml` (see below) file for metadata and a `README.md` file for an in-depth description. 
 
 For the documentation of the module in `README.md`, the following guidelines apply:
 - At the start of each _paragraph_, refer to the module using its name or with "the module", not "it" or "the script".
@@ -37,6 +39,56 @@ For the documentation of the module in `README.md`, the following guidelines app
 For the short module description (`shortdesc:`), the following guidelines apply:
 - The description should start with a phrase like "The glorb module reticulates splines" or "The tree module can be used to plant trees".
 
+### `module.yml`
+
+A `module.yml` is the metadata file for a public module, used on the website to generate module reference pages. May be used in future projects to showcase modules and supply some defaults for them.
+
+#### `name:`
+
+The name of the module, same as the name of the directory and script.
+
+#### `shortdesc:`
+
+A short description of the module, ideally not more than one sentence long. This is used in website metadata or anywhere a shorter module description is needed.
+
+#### `readme:`
+
+The URL to the raw contents of the module’s `README.md` in plain text, not HTML. The README may include a top-level heading for readability, but it will be stripped out in favor of `name:` when the README is ingested for the website.
+
+#### `typespec:`
+
+The URL to the raw contents of the module’s `<modulename>.tsp` [TypeSpec](https://typespec.io/) definition in plain text. This will be used for configuration validation in the editor and CLI, and for generating documentation for the module. Please document each configuration option carefully. 
+
+#### `example:`
+
+A YAML string of example configuration showcasing the configuration options available with inline documentation to describe them. Some of the configuration options may be commented out, with comments describing why one might enable them. The intention here is that the example would be a good place to copy-paste from to get started.
+
+### [TypeSpec](https://typespec.io/) schema
+
+Every module folder should include a `<modulename>.tsp` file containing a model of the module's valid configuration options. This schema syntax should be familiar to programmers used to typed languages, especially TypeScript. The schemas will be compiled to the [JSON Schema](https://json-schema.org/) format and used for validation in editors and CLI.
+
+- When creating a new module, you can get started easily by copying relevant parts of the `.tsp` file of a module with similar configuration.
+  - Make sure to change all references to the module's name.
+  - Here's an example of an empty `.tsp` file for a module. Replace `<module-name>` with the module's name in kebab-case, and `<ModuleName>` with the module's name in PascalCase.
+  ```tsp
+  import "@typespec/json-schema";
+  using TypeSpec.JsonSchema;
+
+  @jsonSchema("/modules/<module-name>.json")
+  model <ModuleName>Module {
+      /** <Short description of the module>
+      * https://blue-build.org/reference/modules/<module-name>/
+      */
+      type: "<module-name>",
+  }
+  ``` 
+- Use docstrings with the `/** */` syntax liberally to describe every option in the configuration.
+  - Even the `type:` key should be documented as in the example above.
+  - See [the TypeSpec documentation](https://typespec.io/docs/language-basics/documentation).
+- Remember to use the `?` syntax to declare all properties which are not required to use the module successfully as optional. Also declare default values when applicable.
+  - See [the TypeSpec documentation](https://typespec.io/docs/language-basics/models#optional-properties).
+- Make sure to add a semicolon `;` to the end of all property definitions. Without this, the schema compilation will fail.
+
 ### Boot-time Modules
 > [!IMPORTANT]  
 > Build-time modules are preferred over boot-time modules for better system reliability.  

modules.json

@@ -1,14 +1,13 @@
 [
+  "https://raw.githubusercontent.com/blue-build/modules/main/modules/files/module.yml",
   "https://raw.githubusercontent.com/blue-build/modules/main/modules/akmods/module.yml",
+  "https://raw.githubusercontent.com/blue-build/modules/main/modules/chezmoi/module.yml",
   "https://raw.githubusercontent.com/blue-build/modules/main/modules/bling/module.yml",
   "https://raw.githubusercontent.com/blue-build/modules/main/modules/brew/module.yml",
-  "https://raw.githubusercontent.com/blue-build/modules/main/modules/chezmoi/module.yml",
   "https://raw.githubusercontent.com/blue-build/modules/main/modules/default-flatpaks/module.yml",
-  "https://raw.githubusercontent.com/blue-build/modules/main/modules/files/module.yml",
   "https://raw.githubusercontent.com/blue-build/modules/main/modules/fonts/module.yml",
   "https://raw.githubusercontent.com/blue-build/modules/main/modules/gnome-extensions/module.yml",
   "https://raw.githubusercontent.com/blue-build/modules/main/modules/gschema-overrides/module.yml",
-  "https://raw.githubusercontent.com/blue-build/modules/main/modules/justfiles/module.yml",
   "https://raw.githubusercontent.com/blue-build/modules/main/modules/rpm-ostree/module.yml",
   "https://raw.githubusercontent.com/blue-build/modules/main/modules/script/module.yml",
   "https://raw.githubusercontent.com/blue-build/modules/main/modules/signing/module.yml",

modules/akmods/akmods.tsp

@@ -0,0 +1,19 @@
+import "@typespec/json-schema";
+using TypeSpec.JsonSchema;
+
+@jsonSchema("/modules/akmods.json")
+model AkmodsModule {
+    /** The akmods module is a tool used for managing and installing kernel modules built by Universal Blue.
+     * https://blue-build.org/reference/modules/akmods/
+     */
+    type: "akmods";
+
+    /** The kernel / image your image is based on.
+     * main: stock kernel / main and nvidia images
+     * asus: asus kernel / asus images
+     * fsync: fsync kernel / bazzite images
+     * surface: surface kernel / surface images
+     */
+    base?: "main" | "asus" | "fsync" | "surface" = "main";
+    install: Array<string>;
+}

modules/akmods/module.yml

@@ -1,6 +1,7 @@
 name: akmods
 shortdesc: The akmods module is a tool used for managing and installing kernel modules built by Universal Blue.
 readme: https://raw.githubusercontent.com/blue-build/modules/main/modules/akmods/README.md
+typespec: https://raw.githubusercontent.com/blue-build/modules/main/modules/akmods/akmods.tsp
 example: |
   type: akmods
   base: asus # if not specified, classic "main" base is used by default

modules/bling/bling.tsp

@@ -0,0 +1,13 @@
+import "@typespec/json-schema";
+using TypeSpec.JsonSchema;
+
+@jsonSchema("/modules/bling.json")
+model BlingModule {
+    /** The bling module can be used to pull in small "bling" into your image. 
+     * https://blue-build.org/reference/modules/bling/
+    */
+    type: "bling";
+
+    /** List of bling submodules to run / things to install onto your system. */
+    install: Array<"ublue-update" | "1password" | "dconf-update-service" | "gnome-vrr" | "laptop" | "flatpaksync">;
+}

modules/bling/module.yml

@@ -1,6 +1,7 @@
 name: bling
 shortdesc: The bling module can be used to pull in small "bling" into your image.
 readme: https://raw.githubusercontent.com/blue-build/modules/main/modules/bling/README.md
+typespec: https://raw.githubusercontent.com/blue-build/modules/main/modules/bling/bling.tsp
 example: |
   type: bling
   install:

modules/brew/brew.tsp

@@ -0,0 +1,34 @@
+import "@typespec/json-schema";
+using TypeSpec.JsonSchema;
+
+@jsonSchema("/modules/brew.json")
+model BrewModule {
+    /** The brew module installs Homebrew / Linuxbrew at build time and ensures the package manager remains up-to-date.
+     * https://blue-build.org/reference/modules/brew/
+    */
+    type: "brew";
+
+    /** Whether to auto-update the Brew binary. */
+    "auto-update"?: boolean = true;
+
+    /** Interval between Brew updates. */
+    "update-interval"?: string = "6h";
+
+    /** Time delay after boot before first Brew update .*/
+    "update-wait-after-boot"?: string = "10min";
+
+    /** Wthether to auto-upgrade Brew packages. */
+    "auto-upgrade"?: boolean = true;
+
+    /** Interval between Brew package upgrades. */
+    "upgrade-interval"?: string = "8h";
+
+    /** Time delay after boot before first Brew package upgrade. */
+    "upgrade-wait-after-boot"?: string = "30min";
+
+    /** Whether to apply nofile limits (limits for number of open files) for Brew installations. */
+    "nofile-limits"?: boolean = false;
+
+    /** Whether to enable Brew analytics. */
+    "brew-analytics"?: boolean = true;
+}

modules/brew/module.yml

@@ -1,13 +1,14 @@
 name: brew
 shortdesc: The brew module installs Homebrew / Linuxbrew at build time and ensures the package manager remains up-to-date.
 readme: https://raw.githubusercontent.com/blue-build/modules/main/modules/brew/README.md
+typespec: https://raw.githubusercontent.com/blue-build/modules/main/modules/brew/brew.tsp
 example: |
   type: brew
   # Auto-update Brew binary
   auto-update: true # Optional - Default: true - Expects type: boolean
   # Interval between Brew updates
   update-interval: '6h' # Optional - Default: '6h' - Expects type: string
-   # Time delay after boot before first Brew update
+  # Time delay after boot before first Brew update
   update-wait-after-boot: '10min' # Optional - Default: '10min' - Expects type: string 
   # Auto-upgrade Brew packages
   auto-upgrade: true # Optional - Default: true - Expects type: boolean    

modules/chezmoi/chezmoi.tsp

@@ -0,0 +1,31 @@
+import "@typespec/json-schema";
+using TypeSpec.JsonSchema;
+
+@jsonSchema("/modules/chezmoi.json")
+model ChezmoiModule {
+    /** The chezmoi module installs the latest chezmoi release at build time, along with services to clone a dotfile repository and keep it up-to-date.
+     * https://blue-build.org/reference/modules/chezmoi/
+    */
+    type: "chezmoi";
+
+    /** Git repository to initialize. */
+    repository: string;
+
+    /** Whether to enable the modules services globally for all users, if false users need to enable services manually. */
+    "all-users"?: boolean = true;
+
+    /** Dotfiles will be updated with this interval. */
+    "run-every"?: string = "1d";
+
+    /** Dotfile updates will wait this long after a boot before running. */
+    "wait-after-boot"?: string = "5m";
+    
+    /** Disable the service that initializes `repository` on users that are logged in or have linger enabled UI. */
+    "disable-init"?: boolean = false;
+
+    /** Disable the timer that updates chezmoi with the set interval. */
+    "disable-update"?: boolean = false;
+
+    /** What to do when file different that exists on your repo is has been changed or exists locally. Accepts "skip" or "replace". */
+    "file-conflict-policy"?: "skip" | "replace" = "skip";
+}

modules/chezmoi/module.yml

@@ -1,6 +1,7 @@
 name: chezmoi
 shortdesc: The chezmoi module installs the latest chezmoi release at build time, along with services to clone a dotfile repository and keep it up-to-date.
 readme: https://raw.githubusercontent.com/blue-build/modules/main/modules/chezmoi/README.md
+typespec: https://raw.githubusercontent.com/blue-build/modules/main/modules/chezmoi/chezmoi.tsp
 example: |
   type: chezmoi
   # Git repository to initialize

modules/default-flatpaks/default-flatpaks.tsp

@@ -0,0 +1,49 @@
+import "@typespec/json-schema";
+using TypeSpec.JsonSchema;
+
+@jsonSchema("/modules/default-flatpaks.json")
+model DefaultFlatpaksModule {
+    /** The default-flatpaks module can be used to install or uninstall flatpaks from a configurable remote on every boot.
+     * https://blue-build.org/reference/modules/default-flatpaks/
+    */
+    type: "default-flatpaks";
+
+    /** Whether to send a notification after the install/uninstall is finished. */
+    notify?: boolean = false;
+
+    /** Configuration for system flatpaks. */
+    system?: {
+        /** URL of the repo to add. Defaults to Flathub's URL. */
+        "repo-url"?: string = "https://dl.flathub.org/repo/flathub.flatpakrepo";
+
+        /** Name for the repo to add. */
+        "repo-name"?: string = "flathub";
+
+        /** Pretty title for the repo to add. Not set by default. */
+        "repo-title"?: string;
+
+        /** List of Flatpak IDs to install from the repo. */
+        install?: Array<string>;
+
+        /** List of Flatpak IDs to remove. */
+        remove?: Array<string>;
+    };
+
+    /** Configuration for user flatpaks. */
+    user?: {
+        /** URL of the repo to add. Defaults to Flathub's URL. */
+        "repo-url"?: string = "https://dl.flathub.org/repo/flathub.flatpakrepo";
+
+        /** Name for the repo to add. */
+        "repo-name"?: string = "flathub";
+
+        /** Pretty title for the repo to add. Not set by default. */
+        "repo-title"?: string;
+
+        /** List of Flatpak IDs to install from the repo. */
+        install?: Array<string>;
+
+        /** List of Flatpak IDs to remove. */
+        remove?: Array<string>;
+    };
+}

modules/default-flatpaks/module.yml

@@ -1,6 +1,7 @@
 name: default-flatpaks
 shortdesc: The default-flatpaks module can be used to install or uninstall flatpaks from a configurable remote on every boot.
 readme: https://raw.githubusercontent.com/blue-build/modules/main/modules/default-flatpaks/README.md
+typespec: https://raw.githubusercontent.com/blue-build/modules/main/modules/default-flatpaks/default-flatpaks.tsp
 example: |
   modules: # configured multiple times to highlight how options are overridden
     - type: default-flatpaks

modules/files/files.tsp

@@ -0,0 +1,13 @@
+import "@typespec/json-schema";
+using TypeSpec.JsonSchema;
+
+@jsonSchema("/modules/files.json")
+model FilesModule {
+    /** Copy files to your image at build time
+     * https://blue-build.org/reference/modules/files/
+     */
+    type: "files";
+
+    /** List of files / folders to copy. Format is: `sourcefile.txt: /destination/file.txt`  */
+    files: Array<Record<string>>;
+}

modules/files/module.yml

@@ -1,6 +1,7 @@
 name: files
 shortdesc: Copy files to your image at build time
 readme: https://raw.githubusercontent.com/blue-build/modules/main/modules/files/README.md
+typespec: https://raw.githubusercontent.com/blue-build/modules/main/modules/files/files.tsp
 example: |
   modules:
     - type: files

modules/fonts/fonts.tsp

@@ -0,0 +1,18 @@
+import "@typespec/json-schema";
+using TypeSpec.JsonSchema;
+
+@jsonSchema("/modules/fonts.json")
+model FontsModule {
+    /** The fonts module can be used to install fonts from Nerd Fonts or Google Fonts. 
+     * https://blue-build.org/reference/modules/fonts/
+    */
+    type: "fonts";
+    
+    fonts: {
+        /** List of Nerd Fonts to install (without the "Nerd Font" suffix). */
+        "nerd-fonts"?: Array<string>;
+
+        /** List of Google Fonts to install. */
+        "google-fonts"?: Array<string>;
+    };
+}

modules/fonts/module.yml

@@ -1,6 +1,7 @@
 name: fonts
 shortdesc: The `fonts` module can be used to install fonts from Nerd Fonts or Google Fonts.
 readme: https://raw.githubusercontent.com/blue-build/modules/main/modules/fonts/README.md
+typespec: https://raw.githubusercontent.com/blue-build/modules/main/modules/fonts/fonts.tsp
 example: |
   type: fonts
   fonts:

modules/gnome-extensions/gnome-extensions.tsp

@@ -0,0 +1,20 @@
+import "@typespec/json-schema";
+using TypeSpec.JsonSchema;
+
+@jsonSchema("/modules/gnome-extensions.json")
+model GnomeExtensionsModule {
+    /** The gnome-extensions module can be used to install GNOME extensions inside system directory.
+     * https://blue-build.org/reference/modules/gnome-extensions/
+     */
+    type: "gnome-extensions";
+
+    /** List of GNOME extensions to install. 
+     * (case sensitive extension names or extension IDs from https://extensions.gnome.org/)
+    */
+    install?: Array<string>;
+
+    /** List of system GNOME extensions to uninstall. 
+     * Only use this to remove extensions not installed by your package manager. Those extensions should be uninstalled using the package manager instead.
+    */
+    uninstall?: Array<string>;
+}

modules/gnome-extensions/module.yml

@@ -1,6 +1,7 @@
 name: gnome-extensions
-shortdesc: The gnome-extensions module can be used to install Gnome extensions inside system directory.
+shortdesc: The gnome-extensions module can be used to install GNOME extensions inside system directory.
 readme: https://raw.githubusercontent.com/blue-build/modules/main/modules/gnome-extensions/README.md
+typespec: https://raw.githubusercontent.com/blue-build/modules/main/modules/gnome-extensions/gnome-extensions.tsp
 example: |
   type: gnome-extensions
   install:

modules/gschema-overrides/gschema-overrides.tsp

@@ -0,0 +1,13 @@
+import "@typespec/json-schema";
+using TypeSpec.JsonSchema;
+
+@jsonSchema("/modules/gschema-overrides.json")
+model GschemaOverridesModule {
+    /** The gschema-overrides module can be used for including system-setting overrides for GTK-based desktop environments.
+     * https://blue-build.org/reference/modules/gschema-overrides/
+    */
+    type: "gschema-overrides";
+
+    /** Gschema override files to test and copy to the correct place. */
+    include?: Array<string>;
+}

modules/gschema-overrides/module.yml

@@ -1,6 +1,7 @@
 name: gschema-overrides
 shortdesc: The `gschema-overrides` module can be used for including system-setting overrides for GTK-based desktop environments.
 readme: https://raw.githubusercontent.com/blue-build/modules/main/modules/gschema-overrides/README.md
+typespec: https://raw.githubusercontent.com/blue-build/modules/main/modules/gschema-overrides/gschema-overrides.tsp
 example: |
   type: gschema-overrides
   include:

modules/justfiles/justfiles.tsp

@@ -0,0 +1,16 @@
+import "@typespec/json-schema";
+using TypeSpec.JsonSchema;
+
+@jsonSchema("/modules/justfiles.json")
+model JustfilesModule {
+    /** The justfiles module makes it easy to include just recipes from multiple files in Universal Blue -based images.
+     * https://blue-build.org/reference/modules/justfiles/
+     */
+    type: "justfiles";
+
+    /** Whether to validate the syntax of the justfiles against `just --fmt`. (warning: can be very unforgiving) */
+    validate?: boolean = false;
+
+    /** List of files or subfolders to include into this image. If omitted, all justfiles will be included. */
+    include?: Array<string>;
+}

modules/justfiles/module.yml

@@ -1,6 +1,7 @@
 name: justfiles
 shortdesc: The justfiles module makes it easy to include just recipes from multiple files in Universal Blue -based images. 
 readme: https://raw.githubusercontent.com/blue-build/modules/main/modules/justfiles/README.md
+typespec: https://raw.githubusercontent.com/blue-build/modules/main/modules/justfiles/justfiles.tsp
 example: |
   type: justfiles
   validate: true

modules/rpm-ostree/module.yml

@@ -1,6 +1,7 @@
 name: rpm-ostree
 shortdesc: The rpm-ostree module offers pseudo-declarative package and repository management using rpm-ostree.
 readme: https://raw.githubusercontent.com/blue-build/modules/main/modules/rpm-ostree/README.md
+typespec: https://raw.githubusercontent.com/blue-build/modules/main/modules/rpm-ostree/rpm-ostree.tsp
 example: |
   type: rpm-ostree
   repos:

modules/rpm-ostree/rpm-ostree.tsp

@@ -0,0 +1,22 @@
+import "@typespec/json-schema";
+using TypeSpec.JsonSchema;
+
+@jsonSchema("/modules/rpm-ostree.json")
+model RpmOstreeModule {
+    /** The rpm-ostree module offers pseudo-declarative package and repository management using rpm-ostree.
+     * https://blue-build.org/reference/modules/rpm-ostree/
+     */
+    type: "rpm-ostree";
+
+    /** List of links to .repo files to download into /etc/yum.repos.d/. */
+    repos?: Array<string>;
+
+    /** List of links to key files to import for installing from custom repositories. */
+    keys?: Array<string>;
+
+    /** List of RPM packages to install. */
+    install?: Array<string>;
+
+    /** List of RPM packages to remove. */
+    remove?: Array<string>;
+}

modules/script/module.yml

@@ -1,6 +1,7 @@
 name: script
 shortdesc: The script module can be used to run arbitrary bash snippets and scripts at image build time.
 readme: https://raw.githubusercontent.com/blue-build/modules/main/modules/script/README.md
+typespec: https://raw.githubusercontent.com/blue-build/modules/main/modules/script/script.tsp
 example: |
   type: script
   snippets:

modules/script/script.tsp

@@ -0,0 +1,16 @@
+import "@typespec/json-schema";
+using TypeSpec.JsonSchema;
+
+@jsonSchema("/modules/script.json")
+model ScriptModule {
+    /** The script module can be used to run arbitrary bash snippets and scripts at image build time.
+     * https://blue-build.org/reference/modules/script/
+     */
+    type: "script";
+
+    /** List of bash one-liners to run. */
+    snippets?: Array<string>;
+
+    /** List of script files to run. */
+    scripts?: Array<string>;
+}

modules/signing/module.yml

@@ -1,5 +1,6 @@
 name: signing
 shortdesc: The signing module is used to install the required signing policies for cosign image verification with rpm-ostree and bootc.
 readme: https://raw.githubusercontent.com/blue-build/modules/main/modules/signing/README.md
+typespec: https://raw.githubusercontent.com/blue-build/modules/main/modules/signing/signing.tsp
 example: |
   type: signing # this sets up the proper policy & signing files for signed images to work fully

modules/signing/signing.tsp

@@ -0,0 +1,10 @@
+import "@typespec/json-schema";
+using TypeSpec.JsonSchema;
+
+@jsonSchema("/modules/signing.json")
+model SigningModule {
+    /** The signing module is used to install the required signing policies for cosign image verification with rpm-ostree and bootc.
+     * https://blue-build.org/reference/modules/signing/
+     */    
+    type: "signing";
+}

modules/systemd/module.yml

@@ -1,23 +1,24 @@
 name: systemd
 shortdesc: The systemd module streamlines the management of systemd units during image building.
 readme: https://raw.githubusercontent.com/blue-build/modules/main/modules/systemd/README.md
+typespec: https://raw.githubusercontent.com/blue-build/modules/main/modules/systemd/systemd.tsp
 example: |
   type: systemd
   system:
     enabled:
       - example.service # Enabled (runs on system boot)
     disabled:
-      - example.target # Disabled (does not run on system boot, unless other unit strictly requires it)
+      - example.target # Disabled (does not run on system boot, unless another unit strictly requires it)
     masked:
       - example.service # Masked (does not run on system boot, under any circumstances)
     unmasked:
       - example.service # Unmasked (runs on system boot, even if previously masked)    
   user:
     enabled:
-      - example.timer # Enabled (runs for the user)
+      - example.timer # Enabled (runs for the users)
     disabled:
-      - example.service # Disabled (does not run for the user, unless other unit strictly requires it)
+      - example.service # Disabled (does not run for the users, unless another unit strictly requires it)
     masked:
-      - example.service # Masked (does not run for the user, under any circumstances) 
+      - example.service # Masked (does not run for the users, under any circumstances) 
     unmasked:
-      - example.service # Unmasked (runs for the user, even if previously masked)
+      - example.service # Unmasked (runs for the users, even if previously masked)

modules/systemd/systemd.tsp

@@ -0,0 +1,40 @@
+import "@typespec/json-schema";
+using TypeSpec.JsonSchema;
+
+@jsonSchema("/modules/systemd.json")
+model SystemdModule {
+    /** The systemd module streamlines the management of systemd units during image building.
+     * https://blue-build.org/reference/modules/systemd/
+     */
+    type: "systemd";
+
+    /** System unit configuration. */
+    system?: {
+        /** List of systemd units to enable. (runs on system boot) */
+        enabled?: Array<string>;
+
+        /** List of systemd units to disable. (does not run on system boot, unless another unit strictly requires it) */
+        disabled?: Array<string>;
+
+        /** List of systemd units to mask. (does not run on system boot, under any circumstances) */
+        masked?: Array<string>;
+
+        /** List of systemd units to unmask. (runs on system boot, even if previously masked) */
+        unmasked?: Array<string>;
+    };
+
+    /** User unit configuration (with --global to make changes for all users). */
+    user?: {
+         /** List of systemd units to enable. (runs for the users) */
+         enabled?: Array<string>;
+
+         /** List of systemd units to disable. (does not run for the users, unless another unit strictly requires it) */
+         disabled?: Array<string>;
+ 
+         /** List of systemd units to mask. (does not run for the users, under any circumstances) */
+         masked?: Array<string>;
+ 
+         /** List of systemd units to unmask. (runs for the users, even if previously masked) */
+         unmasked?: Array<string>;
+    };
+}

modules/yafti/module.yml

@@ -1,6 +1,7 @@
 name: yafti
 shortdesc: The yafti module can be used to install yafti and set it up to run on first boot.
 readme: https://raw.githubusercontent.com/blue-build/modules/main/modules/yafti/README.md
+typespec: https://raw.githubusercontent.com/blue-build/modules/main/modules/yafti/yafti.tsp
 example: |
   type: yafti
   custom-flatpaks:

modules/yafti/yafti.tsp

@@ -0,0 +1,13 @@
+import "@typespec/json-schema";
+using TypeSpec.JsonSchema;
+
+@jsonSchema("/modules/yafti.json")
+model YaftiModule {
+    /** The yafti module can be used to install yafti and set it up to run on first boot.
+     * https://blue-build.org/reference/modules/yafti/
+     */
+    type: "yafti";
+
+    /** List of custom Flatpaks to inject to the default yafti.yml. Format is: `PrettyName: org.example.flatpak_id` */
+    "custom-flatpaks"?: Array<Record<string>>;
+}