Manifest Schema

[dlamkins]

This discussion is to hold comments on what requirements are needed by the package manifests. Ideally the manifest would:

• Mirror the module manifest format as much as possible.
• Have few unique fields.
• Have all fields necessary to adequately display the module in a Blish HUD module/package manager.

Unique fields would be things to suite the needs of a repository UI or to facilitate downloading a module that are unique from the module manifest.

In addition to the information held within the manifest, discussion on the manifest format itself is applicable.

It can be difficult to clarify which manifest you are referring to since there is also a module manifest used by the core application to load metadata in about a module. This discussion is about the manifest used to describe the package for download from this repository. To help avoid confusion, we can refer to them as the module manifest and the package manifest.

[dlamkins]

As it stands, the following fields seem the most appropriate to source from the existing manifest (and matching in schema):

• name — The display name of the module to be used in UIs. 🔗
• namespace — The module's unique identifier. 🔗
• version — The module's version. This should likely match the manifest's name in the repository, as well. 🔗
• contributors — A list of the module's contributors. 🔗
• description — A description of the module suitable to be displayed in the UI. This is an optional field in the module manifest. 🔗
• dependencies — A list of the module's dependencies (including supported Blish HUD version range). This is an optional field in the module manifest. 🔗
• url — A link to either more details about the module or the module's repository. To provide the same purpose as the "Homepage" field in the winget-pkgs format. 🔗
• manifest_version — Used to indicate the schema version of the manifest in case there is a need for breaking changes in the future (same purpose as the module manifest_version, but would not necessarily reflect the same version as in the module manifest as it is not representing the same schema). 🔗

In addition to these fields, the following will be necessary to some degree, as well (with room to decide on actual field names - the ones below are used as an example):

• location — A URL pointing to where the module BHM can be downloaded from. This would be the equivalent of winget's Installers > Url field (which we have a naming conflict with url).
• hash — A SHA256 hash of the module used to ensure the integrity of the module when pulled from the location. This is the equivalent of winget's Installers > Sha256 field.

[dlamkins]

The serialization method of the manifest would likely be best in either JSON or YAML and am open to input for either.

• JSON is used by Blish HUD already for the module manifest which makes it an appealing choice.
• YAML is a bit easier to handle by humans for small manifests like this, but the serializer would introduce an additional dependency in Blish HUD Core.

I suspect that JSON will be the easy answer for this, but wanted to ensure it had a chance to be discussed if others felt differently.

[greaka]

kamil mentioned that release notes might be a good idea to have as a field of the manifest
https://discordapp.com/channels/531175899588984842/726438402521694340/728248100577345547

[dlamkins]

At this time, the original proposal contains the v1 manifest. If later we choose to include more such as release notes, we'll build that into a v2.