Compose the OCI way by javatask · Pull Request #200 · margo/specification

javatask · 2026-07-27T13:20:32Z

Description

Adds Compose-specific typed properties to the Desired State LinkML schema (desired-state.linkml.yaml). Previously, ComposeComponent was an empty subclass inheriting a generic key/value Property bag with no validation. This change introduces a ComposeComponentProperties class with typed, constrained attributes for OCI-based Compose Archive retrieval and deployment:

repository (required) — OCI registry URI (oci://...)
revision (required) — SemVer-compliant OCI tag
wait (optional) — boolean controlling deployment completion semantics
timeout (optional) — max wait duration (##m##s format)

This aligns the desired-state schema with the voted SUP-01 Compose OCI approach and replaces the legacy packageLocation/keyLocation fields that had no integrity guarantee.

Issues Addressed

margo/specification #168 — Define improvements to compose manifest workloads
margo/specification #179 — Fix packagefile location for compose applications
margo/specification #166 — Define standard mechanism for compose-enabled devices to authenticate and pull Compose Archive

Change Type

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.

linux-foundation-easycla · 2026-07-27T13:20:37Z

The committers listed above are authorized under a signed CLA.

✅ login: javatask / name: Andrii Melashchenko (35ccd36, e3ae992)

phil-abb · 2026-07-27T13:36:53Z

@julienduquesnay-se / @merrill-harriman-se - I'm assuming this is a PR you guys would want to review since you're targeting Compose.

phil-abb

This is more of an editorial review since we're not planning to target compose

phil-abb · 2026-07-28T10:27:06Z

-| keyLocation    | string | N  | The public key used to validated the digitally signed package. It is highly recommend to digitally sign the package. When signing the package PGP MUST be used.|
-| wait | bool  | N  | If `True`, indicates the device MUST wait until the Compose file has finished starting up before starting the next Compose file. The default is `True`. The Workload Fleet Management Client MUST support `True` and MAY support `False`. Only applies if multiple `compose` components are provided.|
-| timeout | string      | N   | The time to wait for the component's installation to complete. If the installation does not completed before the timeout occurs the installation process fails. The format is "##m##s" indicating the total number of minutes and seconds to wait.|
+| repository     | string |  Y  | OCI repository URI for the Compose Archive (e.g., `oci://registry.example.com/org/component-name`). MUST be used for Compose components. See [Compose Component Registry](application-registry.md#compose-component-registry) for details.|


With the .md I get a 404 error when following the link. It's an oddity with how the document website renders things. It's either remove this or add ./ to it url.

Suggested change

| repository | string | Y | OCI repository URI for the Compose Archive (e.g., `oci://registry.example.com/org/component-name`). MUST be used for Compose components. See [Compose Component Registry](application-registry.md#compose-component-registry) for details.|

| repository | string | Y | OCI repository URI for the Compose Archive (e.g., `oci://registry.example.com/org/component-name`). MUST be used for Compose components. See [Compose Component Registry](application-registry#compose-component-registry) for details.|

@javatask, this is still an issue

phil-abb · 2026-07-28T10:37:36Z

+
+## Compose Component Registry
+
+Compose components MUST be stored in an OCI-compliant Component Registry and referenced via `repository` (an `oci://` URI) and `revision` (an OCI tag matching SemVer 2.0) in the ApplicationDescription and Desired State manifests.


Suggested change

Compose components MUST be stored in an OCI-compliant Component Registry and referenced via `repository` (an `oci://` URI) and `revision` (an OCI tag matching SemVer 2.0) in the ApplicationDescription and Desired State manifests.

Compose components MUST be stored in an OCI-compliant Component Registry and referenced via `repository` (an `oci://` URI) and `revision` (an OCI tag matching SemVer 2.0) in the ApplicationDescription and ApplicationDeployment manifests.

@javatask this still probably needs changed

sulksamino · 2026-07-30T10:59:16Z

We generate a wfm client from the api spec. I wanted to give this PR a try and noticed that the file was not yet adapted.

The file is at system-design/specification/margo-management-interface/workload-management-api-1.0.0.yaml (it was renamed to system-design/specification/margo-management-interface/workload-management-api-1.0.0-rc.2.yaml on pre-draft)

While creating a temporary solution I also noticed something. I am not very familiar with linkml, but the introduction of the revision attribute on Component in desired-state.linkml.yaml looks like a duplicate and would allow a component to have two (different) revisions:

name: digitron-orchestrator-docker
revision: "2.0.9"
properties:
  repository: oci://northstarida.azurecr.io/compose/digitron-orchestrator
  revision: "1.0.9"
  wait: true
  timeout: "5m0s"

Address PR margo#200 review feedback (phil-abb, sulksamino): - Remove HelmComponent, ComposeComponent (empty subclasses) - Remove HelmDeploymentProfile, ComposeDeploymentProfile (use pattern) - Remove duplicate Component.revision (keep in ComponentProperties only) - Replace Property key/value bag with typed ComponentProperties - Add pattern constraints: oci:// URI, SemVer regex, timeout format - Unify docs: single ComponentProperties table for all deployment types - Fix DesiredState-001.yaml: wait: "true" (string) → wait: true (bool) - Clarify ORAS is example tool, not requirement - Remove WFM from reconciliation subheader Discriminator is now DeploymentProfile.type (pattern: ^(helm|compose)$). Adding new types (e.g. quadlet) requires only a regex update.

Implement Specification Update Proposal SUP-01 which defines the normative Compose Archive packaging model for Margo, following the same OCI registry pattern established for Helm components. Schema changes (application-description.linkml.yaml): - Make repository and revision required for all component types - Add SemVer 2.0 pattern constraint on revision field - Remove packageLocation and keyLocation fields (never released) Schema changes (desired-state.linkml.yaml): - Add optional revision attribute to Component class with SemVer pattern Documentation (application-registry.md): - Add Compose-specific OCI media types to Margo-Specific Media Types table (application/vnd.org.margo.component.compose+json and application/vnd.org.margo.component.compose.tar+gzip) - Add normative Compose Archive Structure section (directory layout, security constraints, integrity verification) - Add publishing workflow guidance (oras push recommended) - Add wait semantics for Compose components Documentation (index.md.jinja2): - Update ComponentProperties compose table to document repository/revision - Remove Investigation Needed block for compose properties Examples: - Update all compose examples to use repository/revision instead of packageLocation/keyLocation Resolves: margo#168, margo#166, margo#179 SUP: specification-enhancements/proposals/compose-oci/sup-01-compose-oci.md Breaking-Change: yes (pre-draft, no backward compat required) Signed-off-by: Andrii Melashchenko <andrii.melashchenko@belden.com>

Address PR margo#200 review feedback (phil-abb, sulksamino): - Remove HelmComponent, ComposeComponent (empty subclasses) - Remove HelmDeploymentProfile, ComposeDeploymentProfile (use pattern) - Remove duplicate Component.revision (keep in ComponentProperties only) - Replace Property key/value bag with typed ComponentProperties - Add pattern constraints: oci:// URI, SemVer regex, timeout format - Unify docs: single ComponentProperties table for all deployment types - Fix DesiredState-001.yaml: wait: "true" (string) → wait: true (bool) - Clarify ORAS is example tool, not requirement - Remove WFM from reconciliation subheader Discriminator is now DeploymentProfile.type (pattern: ^(helm|compose)$). Adding new types (e.g. quadlet) requires only a regex update.

javatask · 2026-07-30T18:04:46Z

@phil-abb @sulksamino I accepted all your comments and updated pull request, please review:
Address PR #200 review feedback (phil-abb, sulksamino):

Remove HelmComponent, ComposeComponent (empty subclasses)
Remove HelmDeploymentProfile, ComposeDeploymentProfile (use pattern)
Remove duplicate Component.revision (keep in ComponentProperties only)
Replace Property key/value bag with typed ComponentProperties
Add pattern constraints: oci:// URI, SemVer regex, timeout format
Unify docs: single ComponentProperties table for all deployment types
Fix DesiredState-001.yaml: wait: "true" (string) → wait: true (bool)
Clarify ORAS is example tool, not requirement
Remove WFM from reconciliation subheader

Discriminator is now DeploymentProfile.type (pattern: ^(helm|compose)$).
Adding new types (e.g. quadlet) requires only a regex update.

phil-abb · 2026-07-30T18:06:03Z

@phil-abb @sulksamino I accepted all your comments and updated pull request, please review:
Address PR #200 review feedback (phil-abb, sulksamino):

@javatask I'll try to take a look at the updates on Friday.

sulksamino · 2026-07-31T07:10:47Z

I still think the openapi spec needs to be adapted (or is there any automation that generates it?). I incorporated your changes into a copy of the openapi spec to get our client generator going. You can adopt them if you want: https://git.flecs.tech/flecs/wfm-client-rs/commit/ae9da06d5e02b7ad6c075f57109b873e03a453c6?files=spec/workload-management-api-1.0.0-rc.2.yaml

phil-abb · 2026-07-31T12:27:06Z

I still think the openapi spec needs to be adapted (or is there any automation that generates it?). I incorporated your changes into a copy of the openapi spec to get our client generator going. You can adopt them if you want: https://git.flecs.tech/flecs/wfm-client-rs/commit/ae9da06d5e02b7ad6c075f57109b873e03a453c6?files=spec/workload-management-api-1.0.0-rc.2.yaml

@javatask yeah, the OpenAPI spec will need to be updated manually right now. There is ongoing work to auto-generate this from the LinkML documents, but it's not ready yet.

javatask assigned matlec, phil-abb and ajcraig Jul 27, 2026

javatask requested a review from a team as a code owner July 27, 2026 13:20

javatask added App Package Improvements Compose Application Type Improvements labels Jul 27, 2026

phil-abb requested review from julienduquesnay-se and merrill-harriman-se July 27, 2026 13:36

phil-abb self-requested a review July 27, 2026 13:37

javatask force-pushed the compose-the-oci-way branch from 89f5ac4 to d1d9ea8 Compare July 27, 2026 13:51

phil-abb reviewed Jul 28, 2026

View reviewed changes

javatask force-pushed the compose-the-oci-way branch from d1d9ea8 to 37f1faa Compare July 30, 2026 17:58

javatask force-pushed the compose-the-oci-way branch from 37f1faa to 280fbc7 Compare July 30, 2026 18:02

javatask added 2 commits July 30, 2026 20:02

javatask force-pushed the compose-the-oci-way branch from 280fbc7 to 35ccd36 Compare July 30, 2026 18:03

	\| repository \| string \| Y \| OCI repository URI for the Compose Archive (e.g., `oci://registry.example.com/org/component-name`). MUST be used for Compose components. See [Compose Component Registry](application-registry.md#compose-component-registry) for details.\|
	\| repository \| string \| Y \| OCI repository URI for the Compose Archive (e.g., `oci://registry.example.com/org/component-name`). MUST be used for Compose components. See [Compose Component Registry](application-registry#compose-component-registry) for details.\|


		## Compose Component Registry

		Compose components MUST be stored in an OCI-compliant Component Registry and referenced via `repository` (an `oci://` URI) and `revision` (an OCI tag matching SemVer 2.0) in the ApplicationDescription and Desired State manifests.

Uh oh!

Conversation

javatask commented Jul 27, 2026

Description

Issues Addressed

Change Type

Checklist

Uh oh!

linux-foundation-easycla Bot commented Jul 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

phil-abb commented Jul 27, 2026

Uh oh!

phil-abb left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

phil-abb Jul 28, 2026

Choose a reason for hiding this comment

Uh oh!

phil-abb Jul 31, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

phil-abb Jul 28, 2026

Choose a reason for hiding this comment

Uh oh!

phil-abb Jul 31, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

sulksamino commented Jul 30, 2026

Uh oh!

javatask commented Jul 30, 2026

Uh oh!

phil-abb commented Jul 30, 2026

Uh oh!

sulksamino commented Jul 31, 2026

Uh oh!

phil-abb commented Jul 31, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

linux-foundation-easycla Bot commented Jul 27, 2026 •

edited

Loading