Application Metadata¶
Metadata for Hermes Applications is specified as a metadata.json file located in the root group
in the HDF5 File.
It is a json document and must conform to the Application metadata json schema to be valid.
Application Metadata Contents¶
The Application Metadata is formally defined by hermes_app_metadata.schema.json.
All Application metadata files MUST conform to that schema, or the Application will be considered invalid.
Diagram: Hermes Application Metadata¶
Note: Diagram is illustrative of metadata contents only.
See hermes_app_metadata.schema.json for the formal definition.
Application identifying Data¶
- Application Name : Single Line name of the application.
- Icon
- Version
- Description - Short Description of the Application
- About - Long form Description of the Application
- Copyright - Copyright Notices
- License - SPDX Strings and/or a Link to a License held within the app image.
Application Developer/Author¶
- Developers Name
- Optional contact information
- Optional payment address
Resources¶
Each application will need a minimum set of resources from Hermes. The Metadata also lists the minimum viable resources required for the application. It should also list what are the resources the Application would like to have available. It can optionally list the maximum allocatable resources which could enable enhanced features or other functions in the application.
If a resource minimum is set as 0, then it means the resource can be denied by the user but the application can still operate.
Permissions¶
When Hermes has permissioned resources, the metadata will list the permissions being requested by the application.
Configuration¶
Other than resourcing and permissions, the metadata.json file does not contain the configuration of the application.
Application configuration is defined by the WASM Component modules.
Metadata Schema¶
Schema: hermes_app_metadata.schema.json
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://raw.githubusercontent.com/input-output-hk/hermes/main/hermes/schemas/hermes_app_metadata.schema.json",
"title": "Application Metadata Schema",
"description": "Metadata which defines a Hermes Application and is carried inside the Hermes Application Package.",
"type": "object",
"additionalProperties": false,
"properties": {
"$schema": {
"type": "string",
"title": "Application Metadata Schema Reference",
"default": "https://raw.githubusercontent.com/input-output-hk/hermes/main/hermes/schemas/hermes_app_metadata.schema.json",
"pattern": "^(https://raw.githubusercontent.com/input-output-hk/hermes/main/hermes/schemas/)|(.*/)hermes_app_metadata.schema.json$",
"description": "Reference to the Application Metadata Schema.\nShould be to https:// this will be validated.\nLocal references are only to simplify development."
},
"name": {
"type": "string",
"title": "Application Name",
"description": "Name of the Application"
},
"version": {
"type": "string",
"title": "Application Version",
"description": "Version of the Application",
"pattern": "^V[0-9]+\\.[0-9]+\\.[0-9]+( .*$)?$"
},
"description": {
"type": "string",
"title": "Application Description",
"description": "Short Description of the Application"
},
"about": {
"type": "string",
"title": "Application About",
"description": "Long form Description of the Application"
},
"src": {
"type": "array",
"title": "Links to the source of this application.",
"description": "Can be links to code repositories or the Authors website.\nSpecifying any `src` is Optional, however if defined, then these URLs must be reachable when the Application is packaged.",
"items": {
"type": "string",
"format": "uri",
"pattern": "^https://[^\\s/?#]+.[^\\s/?#]+(/[^\\s?#]*)?$"
},
"uniqueItems": true,
"minItems": 1
},
"copyright": {
"type": "array",
"title": "Application Copyright",
"description": "List of Copyright Notices/Claims over the Application.\nIf no copyright is claimed then there should be an explicit statement about the Application being in the public domain.",
"items": {
"type": "string"
},
"uniqueItems": true,
"minItems": 1
},
"license": {
"type": "array",
"title": "Application License",
"description": "List of Licenses/Claims over the Application.\nMust declare at least `spdx` or `file`, `note` is Optional.\nIf `file` is specified it must exist within the Package for the Application to be valid.",
"uniqueItems": true,
"minItems": 1,
"items": {
"type": "object",
"additionalProperties": false,
"minProperties": 1,
"$comment": "Validation Should be one or both of `spdx` and `file` and `note` is optional.",
"properties": {
"spdx": {
"type": "string",
"title": "License SPDX ID",
"description": "SPDX ID of the License.\nIn the case of proprietary or non SPDX licenses, do not specify a SPDX ID and just include a license file."
},
"file": {
"type": "string",
"title": "License File",
"description": "Path to the License File inside the Package.\nMust be a `.txt` file and it must exist at Package creation time.\nFile MUST be text, displayable using monospaced fonts and no line exceeds 80 characters.",
"pattern": "^/.*\\.txt$"
},
"note": {
"type": "string",
"title": "License Note",
"description": "Note about the License.\nFor Example: Could limit the license to a particular aspect of the Application or part of the code."
}
}
}
},
"build_date": {
"type": "integer",
"title": "Application Build Date",
"description": "Unix Epoch Timestamp of when the Application was packaged or built.\nThis field will be overwritten if present, by the Hermes packaging system.\nThe field is required, but this will be checked when the package is validated.",
"default": 0
},
"developer": {
"type": "object",
"title": "Application Developer",
"additionalProperties": true,
"properties": {
"name": {
"type": "string",
"title": "Application Developer Name",
"description": "Name of the Developer"
}
},
"required": [
"name"
]
},
"resources": {
"type": "object",
"title": "Application Resources",
"additionalProperties": false,
"properties": {
"file-storage": {
"type": "object",
"title": "Application File Storage Allocation",
"description": "File Storage Allocation of the Application",
"additionalProperties": false,
"properties": {
"minimum": {
"type": "integer",
"title": "Application Minimum File Storage",
"description": "Minimum File Storage of the Application.\nSize is in MegaBytes."
},
"requested": {
"type": "integer",
"title": "Application Requested File Storage",
"description": "Requested File Storage of the Application.\nSize is in MegaBytes."
},
"maximum": {
"type": "integer",
"title": "Application Maximum File Storage",
"description": "Maximum File Storage of the Application.\nSize is in MegaBytes."
}
},
"required": [
"minimum"
]
},
"sqlite-db": {
"type": "object",
"title": "Application SQLite DB Storage Allocation",
"description": "SQLite DB Storage Allocation of the Application",
"additionalProperties": false,
"minProperties": 1,
"properties": {
"minimum": {
"type": "integer",
"title": "Application Minimum SQLite DB Storage",
"description": "Minimum SQLite DB Storage of the Application.\nSize is in MegaBytes."
},
"requested": {
"type": "integer",
"title": "Application Requested SQLite DB Storage",
"description": "Requested SQLite DB Storage of the Application.\nSize is in MegaBytes."
},
"maximum": {
"type": "integer",
"title": "Application Maximum SQLite DB Storage",
"description": "Maximum SQLite DB Storage of the Application.\nSize is in MegaBytes."
}
},
"required": [
"minimum"
]
}
}
},
"permissions": {
"type": "object",
"title": "Application Permissions",
"additionalProperties": false,
"properties": {
"admin": {
"type": "boolean",
"title": "Application requires Admin Privileges",
"description": "Does the application require Admin Privileges.",
"default": false
}
}
}
},
"required": [
"$schema",
"name",
"version",
"description",
"copyright",
"license"
]
}
Metadata Example¶
Example: hermes_app_metadata.json
{
"$schema": "https://raw.githubusercontent.com/input-output-hk/hermes/main/hermes/schemas/hermes_app_metadata.schema.json",
"name": "Athena - Project Catalyst Voting",
"version": "V2.7.3",
"description": "Project Catalyst Innovation Platform",
"about": "About Project Catalyst, long form.\nMulti line.",
"src": [
"https://github.com/input-output-hk/hermes",
"https://github.com/input-output-hk/catalyst-voices"
],
"copyright": [
"Copyright Ⓒ 2024, IOG Singapore."
],
"license": [
{
"spdx": "Apache-2.0",
"file": "/srv/data/apache2.txt",
"note": "Both SPDX and File can be specified together.\nThis allows the text of the License to be shown in any admin UI."
},
{
"spdx": "MIT",
"file": "/srv/data/mit.txt"
},
{
"spdx": "Apache-2.0",
"note": "Just defines the license by the SPDX ID."
},
{
"file": "/srv/data/apache2.txt",
"note": "Just defines the license by the file path."
}
],
"developer": {
"name": "IOG Singapore.",
"contact": "Contact details.",
"payment": "wallet address"
},
"resources": {
"file-storage": {
"minimum": 100,
"requested": 300,
"maximum": 1024
},
"sqlite-db": {
"minimum": 1024,
"requested": 4096,
"maximum": 32768
}
},
"permissions": {
"admin": true
}
}