usm/SPECIFICATION.md

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, 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 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 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 which does not permit commercial distribution.
      • The The Anti-Capitalist Software License (v 1.4) which places restriction on the types of users or organisations that may make use of the software.
      • The JSON License 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 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. 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 describing the resources this package needs at runtime.
  • build (string array, required): Each string must be a ResourceRef describing the resources this package needs at compile (build) time.
  • manage (string arraym required): Each string must be a ResourceRef 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 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