11.4. Application Manifests¶
GEISA’s application management system follows a model similar to Amazon IoT Greengrass or Microsoft Azure IoT in that applications have a recipe, manifest, or other set of metadata describing the requirements and dependencies.
GEISA defines two manifests for each Edge Application: a Vendor Application Manifest and an Application Deployment Manifest.
The Vendor Application Manifest provides information about the Edge Application to the System Operator and EMS, including external communication and dependency requirements and requested resource limits. It is used by an ADM-conformant EMS to inform the System Operator and facilitate secure import of the Edge Application.
The Application Deployment Manifest is the System Operator-approved set of effective deployment parameters for a specific Edge Application. It is based on the Vendor Application Manifest and allows the System Operator to set permissions and resource allocations for the target environment, use case, and security requirements.
The Application Deployment Manifest SHALL also include the EMS-assigned numeric
AppID, corresponding to LwM2M Resource 4050.
A manifest may describe external communication or dependency requirements needed to interact with a Vendor Application Server. It does not deploy or configure a Vendor Application Server.
Warning
Overriding the Vendor Application Manifest may prevent applications from running correctly. If a system operator chooses to override the vendor recommendations, they take responsibility for any related application issues. To enable operational flexibility, the GEISA specification requires that system operators be able to override vendor settings, but operators should be aware of the potential consequences.
The Vendor Application Manifest and Application Deployment Manifest SHALL include:
Vendor-assigned reverse-DNS application name (
app-name)Vendor assigned application names (
app-name) use https://en.wikipedia.org/wiki/Reverse_domain_name_notation Reverse DNS Name Notation, similar to Java packagesGEISA recommends
tld.companyname.geisa.appnamefor application names, for example,com.example.geisa.waveformanalyzer.
Application display name (
name)Description of the application
Version Number of the application
Signature(s) of the application image artifact(s).
The GEISA EE SHALL NOT activate an application unless every signature for every image artifact provided in the manifest is valid.
The Vendor Application Manifest SHALL include:
Compatibility:
GEISA API Minimum Version
GEISA LEE Minimum Version (null for unsupported)
GEISA VEE Minimum Version (null for unsupported)
Waveform Access Required (boolean)
Toolchain target triple following LLVM/Clang target-triple conventions (e.g.
aarch64-unknown-linux-musl,aarch64-unknown-linux-gnu, etc.)Toolchain version
System Resource Limits:
Maximum CPU allocation in percent (optional)
Maximum RAM in KiB
Maximum Persistent Storage in KiB
Maximum Non-persistent Storage in KiB
Maximum number of threads (required for VEE applications, optional for LEE applications)
Off-Device Communication
Each application that performs off-device communication MUST specify the classes, destinations, and daily volume of that communication.
See Off-Device Communication for details.
Daily volumes are specified in Byte units, and daily messages are in message units.
Note
The CPU Archicture string is used by both LEE and VEE. On Linux systems,
the architecture string can be obtained using the arch command, but this
command is not required to be provided. Architecture names used within
GEISA follow the target architecture names used by gcc, llvm, and other
compilers. Triple.cpp provides a cannonical list. [TARGET]
Note
Application messaging is provided through the API and does not require direct access to a network interface.
Note
Requests for IP socket communication in a Vendor Application Manifest are subject to operator approval in the Application Deployment Manifest. The System Operator may approve, narrow, replace, or deny requested destination classes, endpoints, ports, and volume limits according to deployment policy.
External Dependencies
GEISA applications should be as self-contained as possible, with all necessary dependencies, except for the base libraries provided by the EE, contained with the application artifacts.
GEISA does not provide a mechanism for loading arbitrary packages. The external dependencies element in the manifest is used exclusively to indicate that one application depends on another.
Vendor-assigned application name (
app-name) of the application this application depends on.
Default Application Configuration
GEISA applications may need basic information to initialize such as the URL of a server, or settings such as the frequency of reporting. The default application configuration provides an initial set of values that can be used by the System Operator when creating the Application Deployment Manifest.
Note
The system operator should be able to change the configuration information without needing to redeploy the application.
Default Launch Strategy
Includes details such as whether the application should automatically be restarted if it fails, and how many failures with a given period of time constitues a permanent failure.
Auto restart (boolean)
Max failures – number of failures within the restart period after which the application will not be restarted
Restart period – elasped time, in minutes, before the failure count is reset. The first failure starts the timer. If the configured maximum number of failures occurs before the restart period is over, the application is not restarted. Otherwise, the failure count is reset.
Signature(s)
All signatures SHALL be an OpenPGP detached signature packet encoded base64, as per [RFC9580] section 6, with the formatting modifications noted in this specification, and placed in the
signatureValueelement.EMS and Platform implementations SHALL parse the contents of the
signatureValueelement to extract the OpenPGP signature block for evaluation.To ensure a consistent canonical form of the manifest and to avoid the issues of escaping embedded newlines, the
signatureValueshall contain only the concatenated base64 encoded value of the OpenPGP detached signature packet. This means:Implementations MUST not include
-----BEGIN PGP SIGNATURE-----and-----END PGP SIGNATURE-----labels.Implementations MUST not include a newline before the base64 encoded signature.
Implementations MUST not include any newlines within the
signatureValueelement, even if they are escaped (e.g.\\n).Implementations MUST concatenate base64 encoded text into a single continuous string.
Implementations MUST accept
signatureValueelements that contains only the base64/ASCII armor encoded signature packet.Implementations SHOULD not include a checksum or any other characters after the required pad / special processing function characters,
=, as these may cause the JSON file to fail validation.Implementations SHOULD ignore any extra characters beyond the required pad characters,
=.
The Signature Packet shall follow [RFC9580], section 5.2.
The Signature Type ID (as documented in [RFC9580], section 5.2) shall be
0x00, Binary Signature.Signatures for the manifest shall be over the compact JSON encoding of the value of the manifest element, inclusive of the value only and all JSON syntax.
Signatures for application artifacts shall be over the entire binary image file.
Application manifests require at least one signature, though they support multiple signatures.
Application artifacts SHALL be signed by the application publisher
Application artifacts MAY be signed by an application certifier, system operator, or other entity.
Platform implementations SHALL validate all signatures included in a manifest.
Signature blocks SHALL include a
signerRole. Valid values in this version of the specification are: ‘publisher’, ‘operator’, ‘certifier’, and ‘other’.EMS and platform implementations SHALL verify that the signing identity is authorized for its declared
signerRoleunder the operator-approved trust configuration.Vendor application manifests SHALL include a manifest signature with the ‘publisher’
signerRole.Deployment application manifests SHALL include a manifest signature with the ‘operator’
signerRole.
The compact value of an application manifest removes all unnecessary whitespace (i.e. whitespace not part of a JSON element value). This provides a consistent, canonical form of the manifest for calculating the signature.
One way of obtaining the compact value of the manifest element is using the
jq command. For example:
jq -c '.["geisa-application-manifest"].["manifest"]' <
vendor-application-manifest-example.json
yields:
{"$comment":"Core application metadata and vendor-recommended settings.","app-name":"org.lfenergy.geisa.testapp","author":"GEISA Developer","name":"Awesome App","description":"This app makes your device awesome","app-version":"1.0.0 splat","manifest-version":"0.9.0","artifacts":[{"$comment":"Single application artifact example. Additional artifact types may be added in future GEISA revisions.","image-name":"AwesomeApp.tgz","image-type":"appoverlay","image-size":262144,"uncompressed-size":1048576,"signatures":[{"signerRole":"publisher","signatureValue":"iHUEABYKAB0WIQRxKinOVqB1gf+p27IoV+memssgbQUCatYX8QAKCRAoV+memssgbU9zAQChKH9MDC/kCezIAVIiXyn8LWjW+8fzhXqO61Wg375YbQD/TVC7H5sTOT1tlknw+FTOjPN+EgpgvNkfRRQ0d3t6vgg="}]}],"api-access":{"$comment":"Requested GEISA API access. Final granted access remains subject to platform and operator policy.","actuator-control":true,"actuator-status":true,"messaging":true,"instantaneous":false,"sensor":true,"waveform":false,"app-to-app":false,"allowed-actuators":["der-switch"]},"compatibility":{"$comment":"Application requires GEISA API and LEE version 0.9.0, does not require VEE support, and identifies a vendor-defined toolchain target.","GEISA-API":"0.9.0","GEISA-LEE":"0.9.0","GEISA-VEE":null,"toolchain-id":"aarch64-unknown-linux-musl","toolchain-version":"1.0.0"},"default-configuration":{"$comment":"Vendor default configuration values. Operators may override these in the deployment manifest.","volume":11,"turbo-encabulator":"on","oscillation-overthruster":"enabled"},"default-launch-strategy":{"$comment":"Vendor-recommended launch and restart behavior. Final enforcement may be subject to platform and operator policy. The watchdog setting indicates whether the application supports the GEISA application watchdog mechanism.","auto-restart":true,"max-restarts":5,"restart-period":60,"start-timeout":5,"stop-timeout":5,"notify-timeout":5,"watchdog":true},"external-dependencies":[],"communication":{"$comment":"Requested communication access and limits. This example requests messaging access, HAN access, and local outbound network usage with a daily volume limit.","messaging":{"$comment":"Vendor-requested message-bus usage limit.","daily-messages":20},"HAN":true,"local":{"$comment":"Vendor-requested local network usage. Outbound TCP port 80 is permitted in this example.","daily-volume":5000,"outbound":["tcp::80"]}},"resources":{"$comment":"Vendor-requested resource allocation limits for operator review.","app-cpu":20,"app-ram":200,"storage-persistent":2000,"storage-nonpersistent":0}}
Note
The jq command shown above does not include any line breaks or
newlines in its output, but the Sphinx documenation system used by the GEISA
specification adds them in for readability. Manifest signatures are
always over the canonical compact form, without any newlines.
Here is an example of a Vendor Application Manifest:
1{
2 "$comment": "Copyright 2025-2026, Contributors to the Grid Edge Interoperability & Security Alliance (GEISA), a Series of LF Projects, LLC. Licensed under the Apache License, Version 2.0. See LICENSE.",
3 "geisa-application-manifest": {
4 "$comment": "Example vendor application manifest. Defines vendor-supplied application name, compatibility, defaults, requested permissions, and requested resource values before operator review, possible adjustment, and deployment approval.",
5 "manifest": {
6 "$comment": "Core application metadata and vendor-recommended settings.",
7 "app-name": "org.lfenergy.geisa.testapp",
8 "author": "GEISA Developer",
9 "name": "Awesome App",
10 "description": "This app makes your device awesome",
11 "app-version": "1.0.0 splat",
12 "manifest-version": "0.9.0",
13 "artifacts": [
14 {
15 "$comment": "Single application artifact example. Additional artifact types may be added in future GEISA revisions.",
16 "image-name": "AwesomeApp.tgz",
17 "image-type": "appoverlay",
18 "image-size": 262144,
19 "uncompressed-size": 1048576,
20 "signatures": [
21 {
22 "signerRole": "publisher",
23 "signatureValue": "iHUEABYKAB0WIQRxKinOVqB1gf+p27IoV+memssgbQUCatYX8QAKCRAoV+memssgbU9zAQChKH9MDC/kCezIAVIiXyn8LWjW+8fzhXqO61Wg375YbQD/TVC7H5sTOT1tlknw+FTOjPN+EgpgvNkfRRQ0d3t6vgg="
24 }
25 ]
26 }
27 ],
28 "api-access": {
29 "$comment": "Requested GEISA API access. Final granted access remains subject to platform and operator policy.",
30 "actuator-control": true,
31 "actuator-status": true,
32 "messaging": true,
33 "instantaneous": false,
34 "sensor": true,
35 "waveform": false,
36 "app-to-app": false,
37 "allowed-actuators": [ "der-switch" ]
38 },
39 "compatibility": {
40 "$comment": "Application requires GEISA API and LEE version 0.9.0, does not require VEE support, and identifies a vendor-defined toolchain target.",
41 "GEISA-API": "0.9.0",
42 "GEISA-LEE": "0.9.0",
43 "GEISA-VEE": null,
44 "toolchain-id": "aarch64-unknown-linux-musl",
45 "toolchain-version": "1.0.0"
46 },
47 "default-configuration": {
48 "$comment": "Vendor default configuration values. Operators may override these in the deployment manifest.",
49 "volume": 11,
50 "turbo-encabulator": "on",
51 "oscillation-overthruster": "enabled"
52 },
53 "default-launch-strategy": {
54 "$comment": "Vendor-recommended launch and restart behavior. Final enforcement may be subject to platform and operator policy. The watchdog setting indicates whether the application supports the GEISA application watchdog mechanism.",
55 "auto-restart": true,
56 "max-restarts": 5,
57 "restart-period": 60,
58 "start-timeout": 5,
59 "stop-timeout": 5,
60 "notify-timeout": 5,
61 "watchdog": true
62 },
63 "external-dependencies": [],
64 "communication": {
65 "$comment": "Requested communication access and limits. This example requests messaging access, HAN access, and local outbound network usage with a daily volume limit.",
66 "messaging": {
67 "$comment": "Vendor-requested message-bus usage limit.",
68 "daily-messages": 20
69 },
70 "HAN": true,
71 "local": {
72 "$comment": "Vendor-requested local network usage. Outbound TCP port 80 is permitted in this example.",
73 "daily-volume": 5000,
74 "outbound": [
75 "tcp::80"
76 ]
77 }
78 },
79 "resources": {
80 "$comment": "Vendor-requested resource allocation limits for operator review.",
81 "app-cpu": 20,
82 "app-ram": 200,
83 "storage-persistent": 2000,
84 "storage-nonpersistent": 0
85 }
86 },
87 "signatures": [
88 {
89 "signerRole": "publisher",
90 "signatureValue": "iHUEABYKAB0WIQQCLIvtYD2tXkl4o11FeoCWIY0ehwUCavz2yQAKCRBFeoCWIY0eh7owAQCnCpK+Ni6OLTgXjk/oVjdEKn/ncS1iAhfMY/cNe1neGAD/brc56j7iocNWhpVzTwsbxf3ZGTIR5P8wHK9yW8MBHwg="
91 }
92 ]
93 }
94}
Here is an example of an Application Deployment Manifest:
1{
2 "$comment": "Copyright 2025-2026, Contributors to the Grid Edge Interoperability & Security Alliance (GEISA), a Series of LF Projects, LLC. Licensed under the Apache License, Version 2.0. See LICENSE.",
3 "geisa-application-manifest": {
4 "$comment": "Example deployment manifest derived from the vendor application manifest. Shows operator-approved effective settings for deployment on a specific class of platform.",
5 "manifest": {
6 "$comment": "Application name and compatibility are carried forward from the vendor application manifest. Deployment-time changes apply to operator policy, configuration, and allocated resources as defined below.",
7 "app-name": "org.lfenergy.geisa.testapp",
8 "AppID": 42,
9 "author": "GEISA Developer",
10 "name": "Awesome App",
11 "description": "This app makes your device awesome",
12 "app-version": "1.0.0 splat",
13 "manifest-version": "0.9.0",
14 "artifacts": [
15 {
16 "$comment": "Deployment continues to use the same application artifact as the vendor manifest in this example.",
17 "image-name": "AwesomeApp.tgz",
18 "image-type": "appoverlay",
19 "image-size": 262144,
20 "uncompressed-size": 1048576,
21 "signatures": [
22 {
23 "signerRole": "publisher",
24 "signatureValue": "iHUEABYKAB0WIQRxKinOVqB1gf+p27IoV+memssgbQUCatYX8QAKCRAoV+memssgbU9zAQChKH9MDC/kCezIAVIiXyn8LWjW+8fzhXqO61Wg375YbQD/TVC7H5sTOT1tlknw+FTOjPN+EgpgvNkfRRQ0d3t6vgg="
25 }
26 ]
27 }
28 ],
29 "api-access": {
30 "$comment": "Operator denied requested actuator-control, otherwise API access is accepted unchanged from the vendor application manifest in this example.",
31 "actuator-status": true,
32 "actuator-control": false,
33 "messaging": true,
34 "instantaneous": false,
35 "sensor": true,
36 "waveform": false,
37 "app-to-app": false
38 },
39 "compatibility": {
40 "$comment": "Compatibility requirements are aligned with the vendor application manifest at GEISA API and LEE version 0.9.0.",
41 "GEISA-API": "0.9.0",
42 "GEISA-LEE": "0.9.0",
43 "GEISA-VEE": null,
44 "toolchain-id": "aarch64-unknown-linux-musl",
45 "toolchain-version": "1.0.0"
46 },
47 "default-configuration": {
48 "$comment": "Operator override of vendor defaults. Volume is reduced and one feature is disabled for this deployment.",
49 "volume": 8,
50 "turbo-encabulator": "off",
51 "oscillation-overthruster": "enabled"
52 },
53 "default-launch-strategy": {
54 "$comment": "Operator-adjusted restart behavior. Restart count is reduced, restart window is increased, and notify timeout is increased. Final enforcement remains subject to platform policy.",
55 "auto-restart": true,
56 "max-restarts": 3,
57 "restart-period": 120,
58 "start-timeout": 5,
59 "stop-timeout": 5,
60 "notify-timeout": 10,
61 "watchdog": true
62 },
63 "external-dependencies": [],
64 "communication": {
65 "$comment": "Operator-restricted communication limits relative to the vendor manifest.",
66 "messaging": {
67 "$comment": "Deployment reduces permitted daily message-bus usage.",
68 "daily-messages": 10
69 },
70 "HAN": true,
71 "local": {
72 "$comment": "Deployment reduces allowed local network daily volume while preserving the same outbound port access.",
73 "daily-volume": 2500,
74 "outbound": [
75 "tcp::80"
76 ]
77 }
78 },
79 "resources": {
80 "$comment": "Operator-approved resource allocation limits. CPU and persistent storage are reduced relative to the vendor manifest while the other approved limits remain unchanged.",
81 "app-cpu": 15,
82 "app-ram": 200,
83 "storage-persistent": 1500,
84 "storage-nonpersistent": 0
85 }
86 },
87 "signatures": [
88 {
89 "signerRole": "operator",
90 "signatureValue": "iHUEABYKAB0WIQRxKinOVqB1gf+p27IoV+memssgbQUCavz2wgAKCRAoV+memssgbf0OAP9IZ5/SELLsP0mbNeWh21sh0XQN4dBghs1WhpZfFcm/vAEAi3rnNBEH/MZXrIqSJKanWc86HDky+NMuVc+j5AAoigM="
91 }
92 ]
93 }
94}