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 handles application metadata by defining two manifests for each application: a vendor manifest and an operator manifest.

The vendor application manifest provides information about the application to the operator and the edge management system, including any external dependencies and minimum resource requirements. The vendor manifest is used by a GEISA ADM conformant edge management system to inform the operator about the application and to facilitate the secure import of the application.

The operator application manifest is based on the vendor application manifest allowing the operator to customize and tune the application permissions and resource allocations to match their execution environment, intended use case, and security requirements prior to deployment to the execution environment.

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.

GEISA vendor and operator application manifests SHALL include:

  • Vendor assigned Application ID

    • Vendor assigned application IDs use https://en.wikipedia.org/wiki/Reverse_domain_name_notation Reverse DNS Name Notation, similar to Java packages

    • GEISA recommends tld.companyname.geisa.appname for application IDs, for example, com.example.geisa.waveformanalyzer.

  • Name of the application

  • Description of the application

  • Version Number of the application

  • Hash of the application image

    • The GEISA EE shall not activate an application unless the hash of the image matches the hash in the metadata

GEISA vendor manifests 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)

    • GEISA LEE CPU arch string as returned by the Linux arch command:

      • ARM 32-bit: armv7l, armv6l

      • ARM 64-bit: aarch64

      • RISC-V 32-bit: riscv32

      • RISC-V 64-bit: riscv64

      • x86 32-bit: i686

      • X86 64-bit: x86_64, amd64

    • GEISA LEE C library required:

      • glibc

      • musl

      • uClibc

      • uClibc-ng

    • For VEE, a string of the JVM version:

      • Java 8: java8

      • Java 11: java11

      • Java 17: java17

      • Java 21: java21

  • System Resources Required:

    • CPU usage in percent

    • RAM in KiB

    • Persistent Storage in KiB

    • Non-persistent Storage in KiB

    • Max threads/processes

  • 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

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 manifest are subject to operator approval in the deployment manifest. Operators 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 ID 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 settngs 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 operator 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.

  • Vendor Signature

    • Base64 Encoded Signature of the compact JSON encoding of the vendor application manifest.

Note

ToDo: Add details on the signature mechanism.

Here is an example of an 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 identity, compatibility requirements, defaults, requested permissions, and minimum resources prior to operator review or deployment-time override.",
 5        "manifest": {
 6            "$comment": "Core application metadata and vendor-recommended settings.",
 7            "app-id": "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                    "signature": {
21                      "signatureType": "ECDSA",
22                      "signatureLength": 64,
23                      "signatureHex": "AAAABBBBCCCCDDDDEEEEFFFF0000111122223333444455556666777788889999AAAABBBBCCCCDDDDEEEEFFFF0000111122223333444455556666777788889999",
24                      "$comment": "The signature Reference should match the Subject Idenfitier of the signing certificate.",
25                      "signatureReference": "C=US, ST=Any State, L=Any Town, O=Awesome App Publisher"
26                    }
27                }
28            ],
29            "api-access": {
30                "$comment": "Requested GEISA API access. Final granted access remains subject to platform and operator policy.",
31                "actuator-status": true,
32                "actuator-control": true,
33                "messaging": true,
34                "instantaneous": false,
35                "sensor": true,
36                "waveform": false,
37                "app-to-app": false
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-linux-musleabihf neon",
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. Watchdog behavior remains under broader discussion.",
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 minimum resource requirements.",
81                "app-cpu": 20,
82                "threads": 1,
83                "app-ram": 200,
84                "storage-persistent": 2000,
85                "storage-nonpersistent": 0
86            }
87        },
88        "signature": {
89            "signatureType": "ECDSA",
90            "signatureLength": 64,
91            "signatureHex": "0000111122223333444455556666777788889999AAAABBBBCCCCDDDDEEEEFFFFAAAABBBBCCCCDDDDEEEEFFFF0000111122223333444455556666777788889999",
92            "$comment": "The signature Reference should match the Subject Idenfitier of the signing certificate.",
93            "signatureReference": "C=US, ST=Any State, L=Any Town, O=Awesome App Publisher"
94        }
95    }
96}

Here is an example of a deployment 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 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 identity 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-id": "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": "Deployment continues to use the same application artifact as the vendor manifest in this example.",
16                    "image-name": "AwesomeApp.tgz",
17                    "image-type": "appoverlay",
18                    "image-size": 262144,
19                    "uncompressed-size": 1048576,
20                    "signature": {
21                      "signatureType": "ECDSA",
22                      "signatureLength": 64,
23                      "signatureHex": "AAAABBBBCCCCDDDDEEEEFFFF0000111122223333444455556666777788889999AAAABBBBCCCCDDDDEEEEFFFF0000111122223333444455556666777788889999",
24                      "$comment": "The signature Reference should match the Subject Idenfitier of the signing certificate.",
25                      "signatureReference": "C=US, ST=Any State, L=Any Town, O=Awesome App Publisher"
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-linux-musleabihf neon",
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-adjusted resource allocation. CPU and persistent storage are reduced relative to the vendor manifest while other minimum resources remain unchanged.",
81                "app-cpu": 15,
82                "threads": 1,
83                "app-ram": 200,
84                "storage-persistent": 1500,
85                "storage-nonpersistent": 0
86            }
87        },
88        "signature": {
89            "signatureType": "ECDSA",
90            "signatureLength": 64,
91            "signatureHex": "052c3a40b5714de38965291d366a28df034023ed0fd423c004d56d3c1ad20d8e052c3a40b5714de38965291d366a28df034023ed0fd423c004d56d3c1ad20d8e",
92            "$comment": "The signature Reference should match the Subject Idenfitier of the signing certificate.",
93            "signatureReference": "C=US, ST=Any State, L=Any Town, O=Local Electric Utility"
94        }
95    }
96}