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.