margo · julienduquesnay-se · Apr 9, 2026 · May 8, 2026 · May 14, 2026 · May 20, 2026
@@ -66,6 +66,15 @@ classes:
         description: When deploying to Kubernetes, the namespace the manifest is added under. The namespace is chosen by the workload orchestration solution vendor.
         required: true
         rank: 30
+      deviceId:
+        description: >-
+          The id of the device, with hierarchy if applicable, to which the deployment is assigned.
+          To reference a child-device the format is `{device-id}[/{device-id}[/...]]`. <br/>
+          To request the gateway to choose the child-device, use `*` for the last segment in the hierarchy (i.e. `{device-id}[/{device-id}/...]/*`).
+          If the gateway is not capable of autonomously selecting a child-device, it MUST send back a deployment status with error `101 - Unknown child device ID` when `*` is used.
+        required: true
+        pattern: '^[A-Za-z0-9._~-]+(\/[A-Za-z0-9._~-]+)*(\/\*)?$'
+        rank: 40
 
   Annotations:
     description: A class representing annotations.

@@ -6,6 +6,7 @@ metadata:
         id: a3e2f5dc-912e-494f-8395-52cf3769bc06
     name: com-northstartida-digitron-orchestrator-deployment
     namespace: margo-poc
+    deviceId: edge-01
 spec:
     deploymentProfile:
         type: helm

@@ -6,6 +6,7 @@ metadata:
         id: ad9b614e-8912-45f4-a523-372358765def
     name: com-northstartida-digitron-orchestrator-deployment
     namespace: margo-poc
+    deviceId: edge-01
 spec:
     deploymentProfile:
         type: compose

@@ -277,6 +277,7 @@ metadata:
     applicationId: 
   name: 
   namespace: 
+  deviceId: 
 spec:
     deploymentProfile:
         type: 

@@ -37,6 +37,7 @@ POST /api/v1/clients/{clientId}/deployments/{deploymentId}/status
 | apiVersion      | string    | Y    | Identifier of the version the API resource follows.|
 | kind            | string    | Y    | Must be `DeploymentStatusManifest`.|
 | deploymentId    | string    | Y    | The unique identifier UUID of the deployment specification. Needs to be assigned by the Workload Fleet Management Software. |
+| deviceId        | string    | Y    | Id of the device hosting the deployment. Includes the full device hierarchy if applicable. |
 | status          | []status    | Y    | Element that defines overall deployment status. See the [Status Attributes](#status-attributes) section below.|
 | components      | []components    | Y    | Element that defines the individual component's deployment status. See the [Component Attributes](#component-attributes) section below.|
 
@@ -62,9 +63,27 @@ POST /api/v1/clients/{clientId}/deployments/{deploymentId}/status
 | Fields       | Type            | Required?       | Description     |
 |-----------------|-----------------|-----------------|-----------------|
 | code      | string    | Y    | Associated error code following a component failure during installation. |
+| source    | string    | Y    | Identifies the source of the error. It is set to the device id, with its full hierarchy if applicable, of the device generating the error, or to the component name of the component generating the error. |
 | message   | string    | Y    | Associated error message that provides further details to the WFM about the error that was encountered. |
 
-> Note: Error codes and messages are implementation-specific. 
+When the error is generated by a see-thru gateway, the source attribute of the error structure MUST be set to the gateway device id, with its full hierachy if applicable.
+
+When the error is not generated by a see-thru gateway, the source of the `status.error` attribute MUST be set to the name of the deployment as defined in the `metadata.name` attribute of the application deployment manifest. 
+
+When the error is not generated by a see-thru gateway, the source of the `components.error` attribute MUST be set to the name of the component as defined in the `components[].name` for that component.
+
+> Note: Most error codes and messages are implementation-specific. 
+
+> Note: the purpose of the `source` attribute is to avoid collision between reserved error codes and implementation-specific error codes.
+
+##### Reserved codes for gateway-generated errors:
+
+| Error Code | Message | Source | Description |
+|------------|-------------|-------------|-------------|
+| 101        | Unknown child device ID | Id of the gateway | The gateway cannot identify the child device with the given ID. |
+| 102        | Child device unreachable | Id of the gateway | The gateway cannot establish a connection with the child device. |
+
+When the error used is a reserved code for a gateway-generated error, the `source` attribute MUST be set to the id of the gateway, with its full hierachy if applicable.
 
 ## Example Deployment Status Manifest Request
 
@@ -77,6 +96,7 @@ POST /api/v1/clients/{clientId}/deployments/{deploymentId}/status
         "state": "pending",
         "error": {
             "code": "",
+            "source": "",
             "message": ""
         }
     },
@@ -86,6 +106,7 @@ POST /api/v1/clients/{clientId}/deployments/{deploymentId}/status
             "state": "pending",
             "error": {
                 "code":"",
+                "source": "",
                 "message":""
             }
         },
@@ -94,6 +115,7 @@ POST /api/v1/clients/{clientId}/deployments/{deploymentId}/status
             "state": "pending",
             "error": {
                 "code": "",
+                "source": "",
                 "message": ""
             }
         }

@@ -1,6 +1,6 @@
 # Device Capabilities
 
-Devices MUST provide the Workload Fleet Management service with its capabilities and characteristics. This is done by calling the Device API's `device capabilities` endpoint. Reporting the device capabilities is the final step in the onboarding of the device's client. 
+Devices MUST provide the Workload Fleet Management service with their capabilities and characteristics. This is done by calling the Device API's `device capabilities` endpoint. Reporting the device capabilities is the final step in the onboarding of the device's client. 
 
 To ensure the WFM is kept up to date, the device's client MUST send updated capabilities information if any changes occur to the information originally provided (i.e., additional memory is added to the device).
 
@@ -9,24 +9,28 @@ To ensure the WFM is kept up to date, the device's client MUST send updated capa
 ## Route and HTTP Methods
 
 ```https
-POST /api/v1/clients/{clientId}/capabilities
-PUT /api/v1/clients/{clientId}/capabilities
+POST /api/v1/clients/{clientId}/capabilities/{deviceId}
+PUT /api/v1/clients/{clientId}/capabilities/{deviceId}
+DELETE /api/v1/clients/{clientId}/capabilities/{deviceId}
 ```
 
 ### Route Parameters
 
 |Parameter | Type | Required? | Description|
 |----------|------|-----------|------------|
 | {clientId} | string | Y | The unique identifier of the (device) client registered with the WFM during onboarding. |
+| {deviceId} | string | Y | The unique identifier of the device reporting the capabilities. <br/>It must have the following format: "{id}[/{id}[/{id}...]]". The top-level `id` is required and must include only unreserved characters as specified in [RFC3986](https://www.rfc-editor.org/rfc/rfc3986#section-2.3). If reporting capabilties for a child device, the subsequent `id`s are required and must include only unreserved characters as specified in [RFC3986](https://www.rfc-editor.org/rfc/rfc3986#section-2.3). <br/>Using multiple ids in the endpoint does not register multiple devices in a single request, but indicates a hierarchy of devices, with a parent/child relationship. |
 
 ### Response Codes
 
 | Code | Description |
 |------|-------------|
 | 201 OK | The device capabilities document was added, or updated, successfully |
+| 204 No Content | The device capabilities document was deleted successfully. |
 | 400 Bad Request | Missing or invalid content-digest header. Ensure the SHA256 hash of the base64-encoded payload is included. |
 | 401 Unauthorized | Signature verification failed. Ensure you are signing with the correct X.509 private key.  |
 | 403 Forbidden | Client certificate is not trusted or has been revoked. |
+| 404 Not Found | POST, PUT:  No client with the given `clientID` was found. <br/> DELETE: No client with the given `clientID` was found or no device with the given `deviceId` was found for the client. |
 | 422 Unprocessable Content | Request body includes a semantic error.  |
 
 ## Request Body Attributes
@@ -41,12 +45,12 @@ PUT /api/v1/clients/{clientId}/capabilities
 
 | Field       | Type            | Required?       | Description     |
 |-----------------|-----------------|-----------------|-----------------|
-| id     | string    | Y    | Unique deviceID assigned to the device via the Device Owner.|
+| id     | string    | Y    | Unique deviceID assigned to the device via the Device Owner. It must include only unreserved characters as specified in [RFC3986](https://www.rfc-editor.org/rfc/rfc3986#section-2.3) plus the path separator (i.e. '/'). In case of a device behind a gateway, the id field takes the form of a path with the id of the parent gateway, the id of the child device, and the ids of any intermediate devices, i.e., "{gatewayId}/[{intermediateDeviceId/.../]{deviceId}". |
 | vendor        | string    | Y    | Defines the device vendor.|
 | modelNumber        | string    | Y    | Defines the model number of the device.|
 | serialNumber       | string    | Y    | Defines the serial number of the device.|
-| roles         | []string    | Y    | Element that defines the device role it can provide to the Margo environment. MUST be one of the following: Standalone Cluster, Cluster Leader, or Standalone Device |
-| resources            | []Resource    | Y    | Element that defines the device's resources available to the application deployed on the device. See the [Resource Fields](#resources-attributes) section below. |
+| roles         | []string    | Y    | Element that defines the device role it can provide to the Margo environment. MUST be one of the following: Standalone Cluster, Cluster Leader, Standalone Device, or Gateway |
+| resources            | []Resource    | *    | Element that defines the device's resources available to the application deployed on the device. See the [Resource Fields](#resources-attributes) section below. <br/> * The element is required if the device has any of the following roles: Standalone Cluster, Cluster Leader, Standalone Device. |
 
 ### Resources Attributes
 Resources of the specific device being reported to the WFM. Utilized to match with the required resources defined in the application description
@@ -161,4 +165,20 @@ These enumerations are used as vocabularies for attribute values of the `DeviceC
         }
     }
 }
-```
+```
+
+## Gateways considerations
+
+### Opaque gateways
+
+Opaque gateways MUST report the combined capabilities of all the devices they connect to the WFM.
+
+> Example: An opaque gateway has two child-devices. Each child-device has an ARM64 processor with 2 cores, 5 GB of memory, 32 GB of storage, and 1 ethernet interface. The gateway will report capabilities of 2 CPUs (arm64) with 2 cores each, 10 GB of memory, 64 GB of storage, and 2 ethernet interfaces. In addition since the gateway can deploy compose applications on its child-devices it will report the role of "standalone device".
+
+## See-thru gateways
+
+See-thru gateways MUST report their capabilities and the capabilities of each device they connect to the WFM. This is done by calling the `device capabilities` endpoint for the gateway itself and for each device behind the gateway. The `deviceId` in the endpoint is used to indicate the hierarchy of devices, with a parent/child relationship. For example, if a see-thru gateway with `deviceId` "gateway1" connects two devices with `deviceId` "deviceA" and "deviceB", the gateway would call the `device capabilities` endpoint three times with the following `deviceId`s: "gateway1", "gateway1/deviceA", and "gateway1/deviceB". 
+
+When reporting its own capabilities, a see-thru gateway MUST report the role "Gateway". 
+
+If a see-thru gateway is capable of hosting edge applications it MUST report the corresponding role(s) (i.e., "Standalone Device", "Standalone Cluster, and/or "Cluster Leader") and the resources available for these deployments.
@@ -85,7 +85,7 @@ paths:
       - PayloadSignature: []
       summary: Complete onboarding with client certificate
 
-  /api/v1/clients/{clientId}/capabilities:
+  /api/v1/clients/{clientId}/capabilities/{deviceId}:
     post:
       summary: Report device capabilities
       security:
@@ -96,6 +96,11 @@ paths:
           required: true
           schema:
             type: string
+        - name: deviceId
+          in: path
+          required: true
+          schema:
+            $ref: '#/components/schemas/DeviceId'
       requestBody:
         required: true
         content:
@@ -111,6 +116,8 @@ paths:
           description: Signature verification failed. Ensure you are signing with the correct X.509 private key.
         '403':
           description: Client certificate is not trusted or has been revoked.
+        '404':
+          description: No client with the given `clientID` was found.
         '422':
           description: Request body includes a semantic error.
     put:
@@ -123,6 +130,11 @@ paths:
           required: true
           schema:
             type: string
+        - name: deviceId
+          in: path
+          required: true
+          schema:
+            $ref: '#/components/schemas/DeviceId'
       requestBody:
         required: true
         content:
@@ -138,9 +150,36 @@ paths:
           description: Signature verification failed. Ensure you are signing with the correct X.509 private key.
         '403':
           description: Client certificate is not trusted or has been revoked.
+        '404':
+          description: No client with the given `clientID` was found.
         '422':
           description: Request body includes a semantic error.
-
+    delete:
+      summary: Remove device (Unregister)
+      security:
+        - PayloadSignature: []
+      parameters:
+        - name: clientId
+          in: path
+          required: true
+          schema:
+            type: string
+        - name: deviceId
+          in: path
+          required: true
+          schema:
+            $ref: '#/components/schemas/DeviceId'
+      responses:
+        '204':
+          description: Device capabilities removed successfully
+        '400':
+          description: Missing or invalid content-digest header. Ensure the SHA256 hash of the payload is included.
+        '401':
+          description: Signature verification failed. Ensure you are signing with the correct X.509 private key.
+        '403':
+          description: Client certificate is not trusted or has been revoked.
+        '404':
+          description: Client or device not found.
   /api/v1/clients/{clientId}/bundles/{digest}:
     get:
       summary: Retrieve bundle information for a specific device and digest
@@ -440,10 +479,10 @@ components:
           enum: [DeviceCapabilitiesManifest]
         properties:
           type: object
-          required: [id, vendor, modelNumber, serialNumber, roles, resources]
+          required: [id, vendor, modelNumber, serialNumber, roles]
           properties:
             id:
-              type: string
+              $ref: '#/components/schemas/DeviceId'
             vendor:
               type: string
             modelNumber:
@@ -454,7 +493,7 @@ components:
               type: array
               items:
                 type: string
-                enum: [Standalone Cluster, Cluster Leader, Standalone Device]
+                enum: [Standalone Cluster, Cluster Leader, Standalone Device, Gateway]
             resources:
               type: object
               required: [cpu, memory, storage, peripherals, interfaces]
@@ -480,6 +519,18 @@ components:
                   type: array
                   items:
                     $ref: '#/components/schemas/DeviceCommunicationInterface'
+    DeviceId:
+      # format: "{id}[/{id}[/{id}...]]"
+      # Top-level id is required and must include only unreserved characters as specified in RFC3986.
+      # Subsequent ids are optional, but if present must include only unreserved characters as specified in RFC3986.
+      type: string
+      pattern: '^[A-Za-z0-9._~-]+(\/[A-Za-z0-9._~-]+)*$'
+    DeviceId_with_asterisk:
+      # format: "{id}[/{id}[/{id}...]/*]"
+      # Top-level id is required and must include only unreserved characters as specified in RFC3986.
+      # Subsequent ids are optional, but if present must include only Unreserved Characters as specified in RFC3986.
+      type: string
+      pattern: '^[A-Za-z0-9._~-]+(\/[A-Za-z0-9._~-]+)*(\/\*)?$'
 
     ComponentStatus:
       type: object
@@ -495,12 +546,14 @@ components:
           properties:
             code:
               type: string
+            source:
+              type: string
             message:
               type: string
 
     DeploymentStatusManifest:
       type: object
-      required: [apiVersion, kind, deploymentId, status, components]
+      required: [apiVersion, kind, deploymentId, deviceId, status, components]
       properties:
         apiVersion:
           type: string
@@ -509,6 +562,8 @@ components:
           enum: [DeploymentStatusManifest]
         deploymentId:
           type: string
+        deviceId:
+          $ref: '#/components/schemas/DeviceId'
         status:
           type: object
           required: [state]
@@ -521,6 +576,8 @@ components:
               properties:
                 code:
                   type: string
+                source:
+                  type: string
                 message:
                   type: string
         components:
@@ -569,25 +626,29 @@ components:
           $ref: '#/components/schemas/appDeploymentSpec'
     appDeploymentMetadata:
       type: object
-      required: [name]
+      required: [annotations, name, namespace, deviceId]
       properties:
-        id:
-          type: string
-          description: Unique identifier for the application deployment
         name:
           type: string
           description: Name of the resource
         namespace:
           type: string
           description: Namespace of the resource
-        labels:
-          type: object
-          additionalProperties: { type: string }
-          description: Labels for the resource
         annotations:
           type: object
-          additionalProperties: { type: string }
           description: Annotations for the resource
+          properties:
+            id:
+              type: string
+              description: Unique identifier for the deployment specification
+              pattern: "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
+            applicationId:
+              type: string
+              description: Unique identifier for the application
+              pattern: "^[-a-z0-9]{1,200}$"
+        deviceId:
+          $ref: '#/components/schemas/DeviceId_with_asterisk'
+          description: Device ID of the target device for the deployment
     helmApplicationDeploymentProfileComponent:
       type: object
       description: Helm Application Deployment Profile Component