Device ID to Target Name change - Impacts "Device" concepts within the specification by ajcraig · Pull Request #225 · margo/specification

ajcraig · 2026-09-21T19:21:24Z

Description

This PR started with a change to the deviceId to targetName within the device capabilities artifact. After making that change in the specification repo, I realized we needed to alter the concept of "Device" within our workload management focused GA1. Changes proposed in this PR align more towards workloads targeting compute surfaces, which could be a variety of form factors from single devices to multi node clusters.

Issues Addressed

N/A

Change Type

Please select the relevant options:

Fix (change that resolves an issue)
New enhancement (change that adds specification content)
Content edits (change that edits existing content)

Checklist

I have read the CONTRIBUTING document.
My changes adhere to the established patterns, and best practices.

Signed-off-by: Armand Craig <acraig@project.margo.org>

…eId-targetName Signed-off-by: Armand Craig <acraig@project.margo.org>

Signed-off-by: Armand Craig <acraig@project.margo.org>

phil-abb · 2026-09-22T10:25:15Z

+
+* MUST be stable for the lifetime of the target relationship.
+* MUST consist only of unreserved characters as specified in [RFC3986](https://www.rfc-editor.org/rfc/rfc3986#section-2.3) in each path segment.
+* MAY contain `/` separators to represent a see-thru [gateway](../../concepts/gateways/gateways.md) hierarchy, in the form `{name}[/{name}[/{name}...]]`.


should this be:

Suggested change

* MAY contain `/` separators to represent a see-thru [gateway](../../concepts/gateways/gateways.md) hierarchy, in the form `{name}[/{name}[/{name}...]]`.

* MAY contain `/` separators to represent a see-thru [gateway](../../concepts/gateways/gateways.md) hierarchy, in the form `{targetName}[/{targetName}[/{targetName}...]]`.

phil-abb · 2026-09-22T10:28:41Z

 |Parameter | Type | Required? | Description|
 |----------|------|-----------|------------|
-| {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. |
+| {targetName} | string | Y | The name of the target whose capabilities are being reported or deleted. See [Target Names](./api-requirements-and-security.md#target-names). <br/>It must have the following format: "{name}[/{name}[/{name}...]]". The top-level `name` 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 `name`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 names in the endpoint does not register multiple devices in a single request, but indicates a hierarchy of devices, with a parent/child relationship. |


Should this be:

Suggested change

| {targetName} | string | Y | The name of the target whose capabilities are being reported or deleted. See [Target Names](./api-requirements-and-security.md#target-names). <br/>It must have the following format: "{name}[/{name}[/{name}...]]". The top-level `name` 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 `name`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 names in the endpoint does not register multiple devices in a single request, but indicates a hierarchy of devices, with a parent/child relationship. |

| {targetName} | string | Y | The name of the target whose capabilities are being reported or deleted. See [Target Names](./api-requirements-and-security.md#target-names). <br/>It must have the following format: "{targetName}[/{targetName}[/{targetName}...]]". The top-level `targetName` is required and must include only unreserved characters as specified in [RFC3986](https://www.rfc-editor.org/rfc/rfc3986#section-2.3). If reporting capabilities for a child device, the subsequent `targetName`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 target names in the endpoint does not register multiple devices in a single request, but indicates a hierarchy of devices, with a parent/child relationship. |

phil-abb · 2026-09-22T10:32:56Z

 | Field       | Type            | Required?       | Description     |
 |-----------------|-----------------|-----------------|-----------------|
-| 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}". |
+| targetName     | string    | Y    | The name of the target whose capabilities are described. It MUST match the `{targetName}` route parameter. 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 see-thru gateway, the value takes the form of a path with the name of the parent gateway, the names of any intermediate devices, and the name of the child device, i.e., "{gatewayName}/[{intermediateName}/.../]{childName}". See [Target Names](./api-requirements-and-security.md#target-names). |


What should happen if the target names in the route don't match the targetName property?

phil-abb · 2026-09-22T10:36:04Z

+      # format: "{name}[/{name}[/{name}...]]"
+      # Top-level name is required and must include only unreserved characters as specified in RFC3986.
+      # Subsequent names are only used when referencing child devices behind a see-thru gateway, and must include only unreserved characters as specified in RFC3986 when present.
      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 only used when referencing child devices, and must include only unreserved characters as specified in RFC3986 when present.
+    TargetName_with_asterisk:
+      # format: "{name}[/{name}[/{name}...]/*]"
+      # Top-level name is required and must include only unreserved characters as specified in RFC3986.
+      # Subsequent names are only used when referencing child devices behind a see-thru gateway, and must include only unreserved characters as specified in RFC3986 when present.
      type: string


Should this be:

Suggested change

# format: "{name}[/{name}[/{name}...]]"

# Top-level name is required and must include only unreserved characters as specified in RFC3986.

# Subsequent names are only used when referencing child devices behind a see-thru gateway, and must include only unreserved characters as specified in RFC3986 when present.

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 only used when referencing child devices, and must include only unreserved characters as specified in RFC3986 when present.

TargetName_with_asterisk:

# format: "{name}[/{name}[/{name}...]/*]"

# Top-level name is required and must include only unreserved characters as specified in RFC3986.

# Subsequent names are only used when referencing child devices behind a see-thru gateway, and must include only unreserved characters as specified in RFC3986 when present.

type: string

# format: "{targetName}[/{targetName}[/{targetName}...]]"

# Top-level target name is required and must include only unreserved characters as specified in RFC3986.

# Subsequent target names are only used when referencing child devices behind a see-thru gateway, and must include only unreserved characters as specified in RFC3986 when present.

type: string

pattern: '^[A-Za-z0-9._~-]+(\/[A-Za-z0-9._~-]+)*$'

TargetName_with_asterisk:

# format: "{targetName}[/{targetName}[/{targetName}...]/*]"

# Top-level target name is required and must include only unreserved characters as specified in RFC3986.

# Subsequent target names are only used when referencing child devices behind a see-thru gateway, and must include only unreserved characters as specified in RFC3986 when present.

type: string

phil-abb · 2026-09-22T14:24:45Z

Is there a reason we wanted to use targetName instead of just name?

…hrough with a counterpart :) Signed-off-by: Armand Craig <acraig@project.margo.org>

phil-abb · 2026-09-23T10:32:18Z

+
+* MUST be stable for the lifetime of the target relationship.
+* MUST consist only of unreserved characters as specified in [RFC3986](https://www.rfc-editor.org/rfc/rfc3986#section-2.3) in each name.
+* MUST NOT contain more than one `/` separator.


Is this changing the original requirements? Or was this the intention all along?

Was the original intention to allow only two levels: gateway -> child? Or was the intention to allow multiple nested gateways: gateway -> child -> child?

The way the capabilities endpoint was defined in the SUP seemed to indicate that more than two levels were desired:

@julienduquesnay-se - thoughts?

@phil-abb

Good note to highlight, as I'm trying to round out the Ids we use and the rules around them.

Investigating the original SUP, the id parameter is described:

In case of a device behind a gateway, it takes the form of a path with the id of the parent gateway and the id of the child device, i.e., "{device-id}/{device-id}". The top-level {device-id} must be unique for a given {clientId}, and the children {device-id} must be unique for a given parent {device-id

Additionally, all the examples in the SUP are only Parent/Child. No reference of Parent/Child/Child.

IMO, what hops occur from Gateway to Child that the capabiltiies or deployment specs are associated with are not relevant/useful for the WFM.

chrisgclayton · 2026-09-28T15:08:59Z

A general comment on this is a concern around us using human provided friendly names in pathing etc. I agree we need these names and should display them to users etc, but I think it is a mistake we will regret down the road. We do not need to optimize for a user entering the friendly name in the path vs. ids for size, character control etc.

oomichi-melco · 2026-10-02T08:42:55Z

Hi @ajcraig

Thanks for letting me know about this change.

Changes proposed in this PR align more towards workloads targeting compute surfaces, which could be a variety of form factors from single devices to multi node clusters.

I have a question regarding the line above from the PR description.
Does "multi node clusters" refer to multi-node Kubernetes clusters?

If so, it seems the intent of this PR is:

The Kubernetes control plane acts as a gateway.
A Kubernetes worker node acts as a child node.
End users will be able to specify a target worker node when deploying applications.

Is my understanding correct?

phil-abb · 2026-10-02T10:08:06Z

@chrisgclayton

A general comment on this is a concern around us using human provided friendly names in pathing etc. I agree we need these names and should display them to users etc, but I think it is a mistake we will regret down the road. We do not need to optimize for a user entering the friendly name in the path vs. ids for size, character control etc.

Are you proposing to remove the {targetName}[/{targetName}[/{targetName}...]/* concept from the route? If so, I raised the same question in the original SUP. It doesn't seem like the route needs this information since it's in the message body.

The SUP owner wanted to include it to make it look more RESTful.

ajcraig added 3 commits September 11, 2026 12:38

Initial commit of changes - to be refined.

504b892

Signed-off-by: Armand Craig <acraig@project.margo.org>

Merge remote-tracking branch 'origin/pre-draft' into ajc/rename-devic…

d36c77b

…eId-targetName Signed-off-by: Armand Craig <acraig@project.margo.org>

Removal of white space.

a8911cb

Signed-off-by: Armand Craig <acraig@project.margo.org>

phil-abb reviewed Sep 22, 2026

View reviewed changes

Addressed various comments, but now in a rabbit hole I need to work t…

fe2a2ed

…hrough with a counterpart :) Signed-off-by: Armand Craig <acraig@project.margo.org>

phil-abb reviewed Sep 23, 2026

View reviewed changes

matlec mentioned this pull request Sep 28, 2026

MIAF pre-draft security review #226

Open

ajcraig mentioned this pull request Sep 30, 2026

[DRAFT] SUP: Report device hostname with capabilities during onboarding margo/specification-enhancements#101

Draft

phil-abb mentioned this pull request Sep 30, 2026

Replace device capabilities with schema-agnostic device profile and characteristics margo/specification-enhancements#98

Open

Navigation Menu

Device ID to Target Name change - Impacts "Device" concepts within the specification - #225

Device ID to Target Name change - Impacts "Device" concepts within the specification#225
ajcraig wants to merge 4 commits into
pre-draftfrom
ajc/rename-deviceId-targetName

ajcraig commented Sep 21, 2026

Uh oh!

Uh oh!

phil-abb Sep 22, 2026

Uh oh!

phil-abb Sep 22, 2026

Uh oh!

phil-abb Sep 22, 2026 •

edited

Loading

Uh oh!

phil-abb Sep 22, 2026

Uh oh!

phil-abb commented Sep 22, 2026

Uh oh!

phil-abb Sep 23, 2026

Uh oh!

ajcraig Sep 23, 2026

Uh oh!

chrisgclayton commented Sep 28, 2026

Uh oh!

oomichi-melco commented Oct 2, 2026

Uh oh!

phil-abb commented Oct 2, 2026 •

edited

Loading

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

	* MAY contain `/` separators to represent a see-thru [gateway](../../concepts/gateways/gateways.md) hierarchy, in the form `{name}[/{name}[/{name}...]]`.
	* MAY contain `/` separators to represent a see-thru [gateway](../../concepts/gateways/gateways.md) hierarchy, in the form `{targetName}[/{targetName}[/{targetName}...]]`.

Conversation

ajcraig commented Sep 21, 2026

Description

Issues Addressed

Change Type

Checklist

Uh oh!

Uh oh!

phil-abb Sep 22, 2026

Choose a reason for hiding this comment

Uh oh!

phil-abb Sep 22, 2026

Choose a reason for hiding this comment

Uh oh!

phil-abb Sep 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

phil-abb Sep 22, 2026

Choose a reason for hiding this comment

Uh oh!

phil-abb commented Sep 22, 2026

Uh oh!

phil-abb Sep 23, 2026

Choose a reason for hiding this comment

Uh oh!

ajcraig Sep 23, 2026

Choose a reason for hiding this comment

Uh oh!

chrisgclayton commented Sep 28, 2026

Uh oh!

oomichi-melco commented Oct 2, 2026

Uh oh!

phil-abb commented Oct 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

phil-abb Sep 22, 2026 •

edited

Loading

phil-abb commented Oct 2, 2026 •

edited

Loading