# 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`.
- `liceences` (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. 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


                

## Resource References