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>

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>

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!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 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!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

phil-abb Sep 22, 2026 •

edited

Loading