margo · arne-broering · Dec 10, 2025 · Oct 31, 2025 · Nov 5, 2025 · Nov 5, 2025
@@ -99,7 +99,7 @@ jobs:
         with:
           name: generated-documentation
           path: |
-            system-design/specification/application-package/application-description.md
+            system-design/specification/applications/application-description.md
             system-design/specification/margo-management-interface/desired-state.md
 
   pages:

@@ -6,7 +6,7 @@ myenv
 
 # Ignore the generated files:
 system-design/specification/margo-management-interface/desired-state.md
-system-design/specification/application-package/application-description.md
-src/specification/application-package/docs
+system-design/specification/applications/application-description.md
+src/specification/applications/docs
 src/specification/margo-management-interface/docs
 *.code-workspace
@@ -1,5 +1,5 @@
 {
-    "root": "src/specification/application-package",
+    "root": "src/specification/applications",
     "targetclass": "ApplicationDescription",
     "schemafile": "application-description.linkml.yaml",
     "markdowndoc": "application-description.md"

@@ -10,15 +10,15 @@ nav:
       - personas-and-definitions/software-composition.md
   - Overview:
       - overview/envisioned-system-design.md
-      - overview/workloads.md
+      - overview/applications.md
       - overview/workload-fleet-management.md
       - overview/edge-compute-devices.md
       - overview/workload-observability.md
   - Concepts:
-      - Workloads:
-          - concepts/workloads/application-package.md
-          - concepts/workloads/application-registry.md
-          - concepts/workloads/local-registries.md
+      - Applications:
+          - concepts/applications/application-package.md
+          - concepts/applications/application-registry.md
+          - concepts/applications/local-registries.md
       - Workload Fleet Managers:
           - concepts/workload-fleet-managers/device-client-onboarding.md
           - concepts/workload-fleet-managers/device-capabilities.md
@@ -34,8 +34,9 @@ nav:
           - specification/margo-management-interface/desired-state.md
           - specification/margo-management-interface/deployment-status.md
           - specification/margo-management-interface/management-interface-swagger.md
-      - Application Package:
-          - specification/application-package/application-description.md
+      - Applications:
+          - specification/applications/application-description.md
+          - specification/applications/application-registry.md
       - Margo Devices:
           - specification/margo-devices/device-requirements.md
       - Observability: 

@@ -3,10 +3,8 @@ id: http://specification.margo.org/application-schema
 name: ApplicationDescription
 title: Application Description Schema
 description: >-
-  Schema for defining application metadata, deployment profiles, parameters, and configuration. 
-  The purpose of this file is to present the application on an application catalog or marketplace 
-  from where an end user selects the application to hand it over to the Workload Orchestration Software, 
-  which configures it and makes it available for installation on the edge device.
+  Schema for defining application metadata, deployment profiles, and parameters. 
+  The purpose of the Application Description is to enable an application's discovery, configuration, and deployment on edge devices.
 version: 1.0 
 prefixes:
   linkml: https://w3id.org/linkml/
@@ -97,8 +95,7 @@ classes:
         required: true
       catalog:
         description: >-
-          Catalog element specifying the application catalog details used to display the application 
-          in an application catalog or marketplace. 
+          Catalog element specifying the application's metadata for enabling its discovery.
           See the [Catalog](#catalog-attributes) section below.
         rank: 40
         range: Catalog

@@ -1,4 +1,9 @@
-The application description has the purpose of presenting the application, e.g., on an application catalog or marketplace from where an end user selects an application to be installed. The end user defines an `ApplicationDeployment` by specifying [configuration parameters](#defining-configurable-application-parameters) for an `ApplicationDescription`. An `ApplicationDeployment` defines the [desired state](../margo-management-interface/desired-state.md) for an application.
+# Application Description
+
+The purpose of the Application Description is to enable an application's discovery, configuration, and deployment on edge devices.
+To deploy an application the end user specifies values for the [parameters](#defining-configurable-application-parameters) given in 
+an Application Description (e.g., through a UI of the WFM) to instantiate an `ApplicationDeployment`, 
+which defines the [desired state](../margo-management-interface/desired-state.md) for an application.
 
 ### Top-level Attributes
 

@@ -0,0 +1,69 @@
+# Application Package
+
+The Application Package, which is used to [distribute an application](../../overview/applications.md) to be deployed as [workloads](../../personas-and-definitions/technical-lexicon.md#workload) on edge devices, comprises the following elements:
+
+- The **Application Description**: a YAML document with the element `kind` defined as `ApplicationDescription`, which is stored in a file (for example named `margo.yaml`) and contains information about the application's [metadata](../../specification/applications/application-description.md#metadata-attributes) (e.g., name, version, author, etc.), the application [components](../../personas-and-definitions/technical-lexicon.md#component) (e.g.,  Helm charts, Compose Archive), which are defined in [deployment configurations](../../specification/applications/application-description.md#deploymentprofile-attributes), and [configurable application parameters](../../specification/applications/application-description.md#defining-configurable-application-parameters).  There is only one YAML file in the package root of kind `ApplicationDescription`.
+- The **resources**, which are additional files associated with the application (human-readable description, icon, release notes, or license file) that may be used to provide more information about the application (e.g., in a UI such as an [application catalog](../../personas-and-definitions/technical-lexicon.md#application-catalog) of a [WFM](../../personas-and-definitions/technical-lexicon.md#workload-fleet-manager)).
+
+The Application Package is distributed via an [Application Registry](./application-registry.md) and is bundled within a **repository** according to the [OCI distribution specification](https://github.com/opencontainers/distribution-spec/blob/v1.1.0/spec.md).
+All files (i.e., Application Description and resource files) belonging to the Application Package are referenced as *layers* (the equivalent term **blobs** is nowadays preferred and will be used in the rest of this document) by a **manifest** inside the repository.
+The blob of the Application Description file is marked with a **mediaType** value as `application/vnd.margo.app.description.v1+yaml`.
+The blobs of resource files are marked with an according **mediaType** (see list [here](../../specification/applications/application-registry.md#margo-specific-media-types)), e.g., an icon in jpeg format is marked with the mediaTye `application/vnd.margo.app.icon.v1+jpeg`. 
+This is illustrated in the figure below and formally defined [here](../../specification/applications/application-registry.md).
+
+
+``` mermaid
+classDiagram
+direction LR
+    class `my-application-description: Blob` {
+	    mediaType: "application/vnd.margo.app.description.v1+yaml"
+        digest: "sha256:f6b7914..."
+        size: 999
+    }
+
+    class `my-resources-icon: Blob` {
+	    mediaType: "application/vnd.margo.app.icon.v1+jpeg"
+        digest: "sha256:sha256:451410b6adfdce..."
+        size: 5065
+    }
+
+    class `my-margo-app-manifest: Manifest` {
+	    mediaType: "application/vnd.oci.image.manifest.v1+json"
+	    artifactType: "application/vnd.org.margo.app.v1+json"
+    }
+
+    `my-margo-app-manifest: Manifest` o-- `my-application-description: Blob`
+    `my-margo-app-manifest: Manifest` o-- `my-resources-icon: Blob`
+```
+
+
+An application aggregates one or more [components](../../personas-and-definitions/technical-lexicon.md#component). Therefore, the [deployment profiles](../../specification/applications/application-description.md#deploymentprofile-attributes) specified in the [Application Description](../../specification/applications/application-description.md) can be defined as Helm Chart components AND/OR [Compose Archive](../../personas-and-definitions/technical-lexicon.md#compose-archive) components.
+
+Each component links to one or more [OCI Container Images](https://github.com/opencontainers/image-spec).
+The components  referenced in the [Application Description](../../specification/applications/application-description.md) are stored in a [Component Registry](../../personas-and-definitions/technical-lexicon.md#component-registry), and the linked container images are provided via a [Container Image Registry](../../personas-and-definitions/technical-lexicon.md#container-image-registry).
+Registries can be remote (i.e., Internet-accessible) or [local](../../concepts/applications/local-registries.md) (i.e., accessible within a local network infrastructure of the devices). 
+
+ The components are being deployed as workloads on the edge devices:
+
+- To target devices, which deploy workloads using Kubernetes, components need to be defined as Helm charts using [Helm (version 3)](https://helm.sh/docs/topics/charts/).
+- To target devices, which deploy workloads using [Compose](https://www.compose-spec.io/), components need to be packaged as [Compose Archives](../../personas-and-definitions/technical-lexicon.md#compose-archive), i.e., a tarball file containing the `compose.yaml` file and any additional artifacts referenced by the Compose file (e.g., configuration files, environment variable files, etc.). Margo recommends to digitally sign this package and to specify the location of the public key in the `ApplicationDescription` (see `keyLocation` [here](../../specification/applications/application-description.md#componentproperties-attributes)). When digitally signing the package PGP encryption MUST be used.
+
+If either one cannot be implemented it MAY be omitted but Margo RECOMMENDS defining [deployment profiles](../../specification/applications/application-description.md#deploymentprofile-attributes) as both Helm chart **AND** Compose components to strengthen interoperability and applicability.
+
+> **Note**
+> A device running the application will only install the application using either the Compose Archives or the Helm Charts, but not both.
+
+
+Margo will provide more detailed discussion and specification on the following points:
+
+> **Investigation Needed**: Question: do we need to specify the location of a SHA256 hash for the Compose Archive also (similar to the PGP key) in the ApplicationDescription? 
+> We will also discuss how we should handle secure container registries that require a username and password.
+>
+> **Investigation Needed**: We need to determine what impact, if any, using 3rd party helm charts has on being Margo compliant.
+>
+> **Investigation Needed**: Missing in the current specification are ways to define dependencies (e.g., application dependencies) as well as required infrastructure services such as storage, message queues/bus, reverse proxy, or authentication/authorization/accounting.
+
+## Relevant Links
+Please follow the subsequent link to view the technical reference of the `ApplicationDescription` format:
+
+- [Application Description](../../specification/applications/application-description.md)
@@ -0,0 +1,42 @@
+# Application Registry
+
+The Margo specification differentiates 3 kinds of registries: *Application Registries*, *Component Registries*, and *Container Image Registries*.
+
+1. An **Application Registry** hosts Application Packages that define through their [Application Description](../../specification/applications/application-description.md) the application as one or multiple [Components](../../personas-and-definitions/technical-lexicon.md#component).
+2. A **Component Registry** hosts the [Components](../../personas-and-definitions/technical-lexicon.md#component) (which are deployable as *workloads*) and are provided  as **Helm Charts** or **Compose Archives**.
+3. A **Container Image Registry** hosts container images referenced by those Components.
+
+Out of these 3 registries, **only the Application Registry interface is in scope** of the Margo specification and its API definition can be found [here](../../specification/applications/application-registry.md).  
+
+The diagram below illustrates these functionalities and relationships of registries within Margo.
+
+```mermaid
+flowchart
+   A[WFM, or internal Application Catalog] -- Application Descriptions link to --> B[Component Registry] 
+   C[Application Registry] -- Application Descriptions link to --> B
+   B -- hosted Components links to --> D[Container Image Registry]
+   A -->|pulls Application Package | C
+   F[App Developer] -->|uploads Application Package to| C
+   C -->|hosts 0..*| E@{ shape: docs, label: "Application Packages"} 
+   C s1@-->|validates token| H[Authentication Service] 
+   A s2@-->|requests token| H
+   style H stroke-dasharray: 3 6
+   style B fill:#ABC
+   style C fill:#ABC
+   style D fill:#ABC
+   classDef dashed stroke-dasharray: 3,6, stroke-dashoffset: 900;
+   class s1 dashed
+   class s2 dashed
+```
+
+As shown in the figure above, an `Application Developer` uploads an [Application Package](application-package.md) to an Application Registry. From there, it is available to a `Workload Fleet Manager` (WFM).
+The WFM acts as a client to pull an [Application Package](application-package.md) from the Application Registry. It would then list this Application Package on its UI (e.g., an internal `Application Catalog`) to enable the usage on its managed devices.
+
+> Note: The figure above shows an `Authentication Service` that manages access control for the Application Registry. This service and interactions with it are not yet formally defined by Margo and needs to be further discussed in the future. The idea here is that the WFM requests a token from the Authentication Service to include in requests to the Application Registry. The received token is then validated by the Application Registry through interaction with the Authentication Service.
+
+The Application Registry's API is compliant with the [OCI Registry API (v1.1.0)](https://github.com/opencontainers/distribution-spec/blob/v1.1.0/spec.md).
+A hosted Application Package is provided by listing its parts as blobs in an [image manifests](https://github.com/opencontainers/image-spec/blob/v1.0.1/manifest.md) that can be requested through the API.
+
+
+## Relevant Links
+* The technical reference of the Application Registry API is defined [here](../../specification/applications/application-registry.md).