# USM Manifest JSON Schema Specification

## Overview

The USM (Universal Source Manifest) is a JSON-based format that defines the structure and metadata of a software package. It provides all necessary information for building, installing, and managing software packages across different systems.

The manifest file must be named named `MANIFEST.usm` and is located at the root of a software project.

## Schema Structure

The USM manifest file is contains a JSON object with the following properties:

- `name` (string, required): The name of the software package (no spaces allowed).
- `version` (string, required): The semantic version of the package, with an optional package version separated by a `+`, e.g.: 
    - `"1.1.2"` for a regular release.
    - `"1.1.2+1` for the same version, but with a fix to the packaging.
- `summary` (string, required): A short summary describing the package, e.g. `Universal Source Manifest` for the package `usm`.
- `licences` (array, required): A list of licences applicable to this package, the array contains a license object with thr following required properties:
    - `name` (string, required): The name of the licence.
    - `text` (string, required): The path, relative to the MANIFEST.usm of the full text of the licence.
    - `category` (string, required): Must be one of:
        - `"libre"`: for software that meets the [four essential freedoms](https://www.gnu.org/philosophy/free-sw.en.html#fs-definition), that being (from gnu.org):
            - The freedom to run the program as you wish, for any purpose (freedom 0).
            - The freedom to study how the program works, and change it so it does your computing as you wish (freedom 1). Access to the source code is a precondition for this.
            - The freedom to redistribute copies so you can help others (freedom 2).
            - The freedom to distribute copies of your modified versions to others (freedom 3). By doing this you can give the whole community a chance to benefit from your changes. Access to the source code is a precondition for this.
        - `"open-source"`: for software which may be regarded as "open source" but fall short of the free software definition. In cases where an "open-source" licence *does* meet all the criteria to be considered free/libre software (by the above definition), `"libre"` must be used instead. Examples of licences considered open-source but not libre include:
            - The [NASA Open Source Agreement v1.3](https://directory.fsf.org/wiki/License:NASA-1.3) is not recognised as a "libre" licence because it includes a provision requiring changes to be your “original creation”, conflicting with "freedom 1" since you cannot make changes that incorporate intellectual property that may be under a permissive licence.
            - The [Artistic-1.0](https://directory.fsf.org/wiki/License:Artistic-1.0) licence is too vague and might not protect the user's freedoms.
        - `"source-available"`: for software that makes the full source code available, but has restrictions on what the user can do with the software, or the source code. Examples include:
            - The [Microsoft Shared Source CLI, C#, and Jscript License](https://directory.fsf.org/wiki/License:Ms-SS) which does not permit commercial distribution.
            - The [The Anti-Capitalist Software License (v 1.4)](https://directory.fsf.org/wiki/License:ANTI-1.4) which places restriction on the types of users or organisations that may make use of the software.
            - The [JSON License](https://directory.fsf.org/wiki/License:JSON) which mandates that "The Software shall be used for Good, not Evil", thereby violating freedom 0 above.
        - `"proprietary"`: for everything else.
- `provides` (object, required): An dictionary object containting properties describing the resources that this software package provides:
    - The property name must be a [ResourceRef](#resource-references) string describing a resource that this package provides.
    - The value may be either:
        - An object with the following properties:
            - `path` (string): The path to the resource file, relative to `pathBase`. Required when `type` is `"reg"` and `pathBase` is not `"as-expected"`, must not be set otherwise.
            - `pathBase` (string): What the `path` property is relative to (see [Installation Lifecycle Directories](#installation-lifecycle-directories)). It is required when `type` is `"reg"` and must not be set otherwise. It can be set to one of the following:
                - `"source"`: referencing the path to the extracted source code.
                - `"build"`: referencing the path to the built output (e.g. where the result of `make` might go).
                - `"install"`: referencing the path to the install output (e.g. where the result of `make install` might go).
                - `"as-expected"` which will copy the file from the install output (e.g. where the result of `make install` might go) in the place expected for a resource of the type and name specified by the [ResourceRef](#resource-references). When in use, `path` must be an empty string.
            - `type` (string, required): The type of filesystem entry for this resource, can be one of the following:
                - `"reg"`: For regular files.
                - `"dir"`: For making directories.
                - `"lnk"`: For symbolic links.
            - `dest` (string): The destination for the symbolic link. Required when `type` is `"lnk"` and must not be set otherwise.
            - `keepOn` (string array): For setting restrictions on deleting this resource, each string in the array can be one of the following:
                - `"final"`: To inhibit deletion when the package is being uninstalled at the request of the user.
                - `"upgrade"`: To inhibit deletion of the resource when the package is being uninstalled to make way for an updated version.
                - `"downgrade"`: To inhibit deletion of the resource when the package is being uninstalled to make way for an older version.
            - `skipFor` (sting array): For setting restrictions on installing this resource, each string in the array can be one of the following:
                - `"fresh"`: To inhibit installation of the resource when the package is being installed for the first time.
                - `"upgrade"`: To inhibit the installation of the resource when the package is being updated to a newer version.
                - `"downgrade"`: To inhibit the installation of the resource when the package is being downgraded to an older version.
        - A shorthand string in the format `[path-base]:[path]` describing the file path to the resource so that it can be copied on installation (see `pathBase` and `path` properties above).
        - The literal string `"as-expected"` (sans colon) which has the same meaning as `{"pathBase": "as-expected"}` above.
- `depends` (object, required): An object with the following properties describing different kinds of package dependencies:
    - `runtime` (string array, required): Each string must be a [ResourceRef](#resource-references) describing the resources this package needs at runtime.
    - `build` (string array, required): Each string must be a [ResourceRef](#resource-references) describing the resources this package needs at compile (build) time.
    - `manage` (string arraym required): Each string must be a [ResourceRef](#resource-references) describing the resources needed to run the processes specified in the `execs` section of the manifest (other than `acquire`).
    - `acquire` (string array): Each string must be a [ResourceRef](#resource-references) describing the resources this package needs to run the acquire script (when specified on the `acquire` property of the `execs` object).
- `flags` (string array, required): A list of flags for this manifest, each string in the array can be one of the following:
    - `"buildInSourceTree"` to tell usm to not create a separate build directory, and compile the package "in place".
    - `"setManifestPropertyEnvs"` idk TODO
- `execs` (object, required): An object describing executable scripts for different phases of the package lifecycle (see [Executable Scripts](#executable-scripts)). It has the following properties :
    - `build` (string, required): Path to the build script relative to the package root.
    - `install` (string, optional): Path to the install script relative to the package root.
    - `remove` (string, optional): Path to the removal script relative to the package root.
    - `postInstall` (string, optional): Path to the post-install script relative to the package root.
    - `acquire` (string, optional): Path to the acquire script relative to the package root.
- `md` (string, optional): Path to a markdown file containing a detailed description of the package, relative to the package root.
- `url` (string, optional): URL to the project's website or repository.
- `screenshots` (string array, optional): Array of paths to screenshot files, relative to the package root.
- `icon` (string, optional): Path to an icon file for the package, relative to the package root.
- `metainfo` (string, optional): Path to a metainfo file following the AppStream specification, relative to the package root.
- `git` (object, optional): Git repository information with the following properties:
    - `origin` (string, required): URL to the git repository.
    - `commit` (string, required): Specific commit hash, tag, or branch to use.
- `extras` (object, optional): Additional properties that don't fit into the standard schema.

## Resource References

Resource references are strings in the format `[resource-type]:[resource-name]` that identify specific resources provided or required by a package. The resource type determines where the resource is located or expected to be found on the filesystem.

### Resource Types

The following resource types are defined:

- `rootpath`: A resource located at the root of the filesystem (`/[resource-name]`).
- `path`: A resource located in the `/usr` hierarchy (`/usr/[resource-name]`).
- `opt`: A resource located in the `/opt` hierarchy (`/opt/[resource-name]`).
- `res`: A resource located in the `/usr/share` hierarchy (`/usr/share/[resource-name]`).
- `cfg`: A resource located in the `/etc` hierarchy (`/etc/[resource-name]`).
- `bin`: An executable binary located in the system PATH.
- `sbin`: A system executable binary located in `/usr/sbin` or `/sbin`.
- `lib`: A shared library located in the system library paths.
- `libexec`: A library executable located in `/usr/libexec`.
- `libres`: A library resource located in `/usr/lib`, `/usr/lib64`, `/lib`, or `/lib64`.
- `info`: An info page located in `/usr/share/info`.
- `man`: A manual page located in `/usr/share/man`.
- `locale`: A locale resource located in `/usr/share/locale`.
- `app`: An application desktop file located in `/usr/share/applications`.
- `inc`: A C/C++ header file located in `/usr/include`.
- `pc`: A pkg-config file located in the system pkg-config paths.
- `vapi`: A Vala API file located in `/usr/share/vala/vapi` or `/usr/share/vala-0.56/vapi`.
- `gir`: A GObject Introspection file located in `/usr/share/gir`.
- `typelib`: A GObject typelib file located in `/usr/lib64/girepository-1.0`, `/usr/lib/girepository-1.0`, `/lib64/girepository-1.0`, or `/lib/girepository-1.0`.
- `tag`: A tag resource managed by the USM system.

### Example Resource References

- `bin:ls`: The `ls` executable binary.
- `lib:libc.so.6`: The libc shared library.
- `man:ls.1`: The manual page for the `ls` command.
- `cfg:myapp.conf`: A configuration file for `myapp`.
- `app:myapp.desktop`: A desktop entry for `myapp`.

## Installation Lifecycle Directories

Each of these directories are created by USM at runtime for each package.

- The source directory (`"pathBase": "source"`) is where the source code is extracted to (in the case of a `.usmc` package), or acquired into (when using an `acquire` exec).
- The build directory (`"pathBase": "build"`) is where the `build` exec is instructed to output the built program to.
- The install directory (`"pathBase": "install"`) is where the `install` exec (if applicable) is instructed to install the program to (i.e. the `DESTDIR` in most build systems).


## Executable Scripts

All executable scripts except for `remove` and `postInstall` are run from the source directory (see above). They may be anywhere in the source package, but are often placed in a folder at the root of the package called `scripts`.

- `build` is the only required exec script, it has the needed commands to actually compile the program from source. The build directory is passed to this exec as the first argument.
- `install` when specified will install the files into the install directory, in the same structure that it would if that directory were the filesystem root. The build directory is passed to this exec as the first argument, the install directory is passed as the second argument, and the install type ("fresh", "upgrade", "downgrade") is passed as the third argument.
- `remove` is called just before USM deletes the resources of a package on uninstallation. The remove type ("final", "upgrade", "downgrade") is passed as the first argument.
- `postInstall` is called after USM has installed the packages resources to the system. The build directory is passed to this exec as the first argument, and the install type ("fresh", "upgrade", "downgrade") is passed as the second argument.
- `acquire` is used to download the authoritative sources. It is usually used by package maintainers when a project does not natively have `MANIFEST.usm` support to enable putting many USM manifests into a repository, and using tooling to download and extract the sources to make `.usmc` (USM Complete) packages. This script usually consists of either a `git clone` command, or a `wget` call followed by an archive extraction command. No parameters are passed to this exec.