Define v1 OCI annotation spec for cloud native AI model artifacts - issue 1740 by savitharaghunathan · Pull Request #2299 · cncf/toc

savitharaghunathan · 2026-09-10T12:55:19Z

Adds a draft v1 OCI annotation spec for the interoperability profile scoped in #1740, covering identity, MOF classification, and supply chain trust metadata for model artifacts.

Signed-off-by: Savitha Raghunathan <saveetha13@gmail.com>

caldeirav

MOF Component Vocabulary is defined in MOF Specifications:
Datasets, Data Preprocessing Code, Model Architecture, Final Model Parameters, Intermediate Model Parameters, Model Metadata, Training Code, Inference Code, Evaluation Code, Evaluation Data, Evaluation Results, Supporting libraries and Tools, Model Card, Data Card, Technical Report, Research Paper, Sample Model Outputs, Model Openness Configuration File

Also the Model Openness Configuration File MUST be included in any distribution.

Do we want to consider the possibility of handling multi-license clarity at the component level here - given that standard open licenses that SHOULD be used for each component from MOF perspective? Note that compoenents and mapping is included in the Model Openness Configuration File.

Signed-off-by: Savitha Raghunathan <saveetha13@gmail.com>

savitharaghunathan · 2026-09-17T17:41:23Z

@caldeirav, thanks for the review. I have updated the mof.components to use the MOF vocabulary and made the Model Openness Configuration file mandatory in every distribution regardless of claimed class. PTAL when you get a chance.

for the multi-license clarity, I am not sure how nesting would work in OCI annotations if we include the contents of the Model Openness Configuration file. @sabre1041 might be able to provide more insight. I am tracking this as an open question for now.

kdubois · 2026-09-18T11:36:28Z

+relationship or an attached attestation. That expectation applies to every row in the "Evidence
+requirement" column below, not just the ones that spell it out.
+
+## Annotation table


Just a formatting thing, but the table is pretty hard to read (https://github.com/savitharaghunathan/toc/blob/9fa8c6bb756cadad35a13e912e22e24986f0e7b4/tags/tag-developer-experience/initiatives/cloud-native-oci-compliant-inner-loop/annotations.md). any way to improve the formatting?

Thanks, @kdubois :) combined the columns for description and evidence into one. PTAL :)

sabre1041 · 2026-09-20T20:27:40Z

@caldeirav, thanks for the review. I have updated the mof.components to use the MOF vocabulary and made the Model Openness Configuration file mandatory in every distribution regardless of claimed class. PTAL when you get a chance.

for the multi-license clarity, I am not sure how nesting would work in OCI annotations if we include the contents of the Model Openness Configuration file. @sabre1041 might be able to provide more insight. I am tracking this as an open question for now.

From a OCI side, since there is no explicit requirement that dependent licenses be included in the final determination of the license(s) that are applied to an artifact, no additional consideration needs to be made. Licenses from dependencies should appear as part of an SBOM that is generated and associated with the artifact (via a relationship from the Referrers API)

sabre1041 · 2026-09-21T07:44:51Z

+3. **Composite bundles** — how `mof.class` and trust metadata roll up when multiple compliant
+   artifacts ship together isn't solved here; it's deferred to the README's relationship
+   metadata work.
+4. **Worked example** — this table should get run through a full example manifest end to end


Suggested change

4. **Worked example** — this table should get run through a full example manifest end to end

4. **Reference Implementation** — this table should get run through a full example manifest end to end

What does "table" mean in this case?

elaborated this to convey the idea of ref impl. PTAL :)

Signed-off-by: Savitha Raghunathan <saveetha13@gmail.com>

savitharaghunathan · 2026-09-21T15:03:15Z

Thanks, @sabre1041, @kdubois, and @caldeirav :) I have addressed the review comments and feedback to the best of my ability. PTAL, when you get some time :)

danieloh30 · 2026-09-24T06:05:15Z

+the bundle carries its own manifest, and how they relate to each other is handled separately
+under the README's "Relationship Metadata" work. So, `mof.class` and the other fields below
+always describe the single artifact the manifest is attached to, never a bundle.
+


Might need to clarify what happens when a developer on their local machine runs podman or oras to pull an adapter.

Consider adding a clarifying sentence: "For local developer workflows (inner loop), runtime tools pulling an adapter artifact should inspect its manifest to resolve its base model dependency via the OCI Referrers API (subject field) rather than expecting the adapter manifest to embed base model weights."

danieloh30 · 2026-09-24T06:05:55Z

+under the README's "Relationship Metadata" work. So, `mof.class` and the other fields below
+always describe the single artifact the manifest is attached to, never a bundle.
+
+## Requirement levels and evidence


Looks excellent. Disambiguating static annotation claims from cryptographically resolvable evidence (OCI referrers/attestations) is crucial for supply chain integrity.

danieloh30 · 2026-09-24T06:07:18Z

+| Key | Requirement | Values | Description |
+|---|---|---|---|
+| `org.cncf.ai.interop.profile.version` | MUST | Semantic version (e.g. `1.0.0`) | Which version of this profile the manifest conforms to. Not the same as the artifact's own version — see `org.opencontainers.image.version` below. |
+| `org.cncf.ai.artifact.type` | MUST | `model` (only valid value in v1); future versions may add `skill`, `rag-context`, `workflow` | Type of AI artifact the manifest represents. |


In addition to "model", consider explicitly reserving lora-adapter or gguf-quant in the description for future compatibility, even if v1 treats adapters as models.

danieloh30 · 2026-09-24T06:08:15Z

+| `org.cncf.ai.interop.profile.version` | MUST | Semantic version (e.g. `1.0.0`) | Which version of this profile the manifest conforms to. Not the same as the artifact's own version — see `org.opencontainers.image.version` below. |
+| `org.cncf.ai.artifact.type` | MUST | `model` (only valid value in v1); future versions may add `skill`, `rag-context`, `workflow` | Type of AI artifact the manifest represents. |
+| `org.cncf.ai.lifecycle.status` | MUST | `experimental`, `validated`, `deprecated`, `product-ready` | Maturity/promotion status, separate from structural conformance — an artifact can be fully compliant and still `experimental`. A GitOps policy could gate promotion on this value. |
+| `org.cncf.ai.model.mof.class` | MUST | `I`, `II`, `III` | LF AI & Data Model Openness Framework class claimed for this artifact (see Unit of conformance above for what "this artifact" means). Requires `mof.components` to be present and consistent with the claimed class, and may require a resolvable MOF-generated model/data card. |


Ensure the MOF class validation logic is supported by local CLI tooling (e.g., oras or podman-ai-lab).

danieloh30 · 2026-09-24T06:09:09Z

+| `org.cncf.ai.lifecycle.status` | MUST | `experimental`, `validated`, `deprecated`, `product-ready` | Maturity/promotion status, separate from structural conformance — an artifact can be fully compliant and still `experimental`. A GitOps policy could gate promotion on this value. |
+| `org.cncf.ai.model.mof.class` | MUST | `I`, `II`, `III` | LF AI & Data Model Openness Framework class claimed for this artifact (see Unit of conformance above for what "this artifact" means). Requires `mof.components` to be present and consistent with the claimed class, and may require a resolvable MOF-generated model/data card. |
+| `org.cncf.ai.model.mof.version` | MUST | MOF spec version, e.g. `1.0` | Which MOF spec version the class/components were derived from. |
+| `org.cncf.ai.model.mof.components` | MUST | Comma-separated list drawn from: `datasets`, `data-preprocessing-code`, `model-architecture`, `final-model-parameters`, `intermediate-model-parameters`, `model-metadata`, `training-code`, `inference-code`, `evaluation-code`, `evaluation-data`, `evaluation-results`, `supporting-libraries-and-tools`, `model-card`, `data-card`, `technical-report`, `research-paper`, `sample-model-outputs`, `model-openness-config-file` | Which MOF components are present. `model-openness-config-file` is always required regardless of class and must itself be resolvable; other values must match the vocabulary listed. |


Comma-separated strings inside OCI annotations can cause parsing inconsistencies across different tools. Consider specifying whether strict whitespace handling (e.g., no spaces after commas: datasets,model-card) is required.

danieloh30 · 2026-09-24T06:10:58Z

+| `org.cncf.ai.security.signing.framework` | MUST | `sigstore`, `notation` (Notary v2/TUF-based) | Framework used to sign the artifact. The signature must be resolvable and verify against the artifact digest — the annotation alone isn't enough. |
+| `org.cncf.ai.security.sbom.format` | MUST | `spdx`, `cyclonedx` | Format of the attached SBOM, which must be resolvable (e.g. via OCI referrers) and tied to this artifact's digest. |
+| `org.cncf.ai.security.provenance.type` | MUST | `slsa-v1.0`, `in-toto` | Type of provenance attestation, which must be resolvable with a subject digest matching this artifact. |
+| `org.cncf.ai.packaging.format` | SHOULD | `modelpack` | Packaging format of the assembled content. Omit if not defined. |


Consider also referencing gguf, safetensors, or onnx if the packaging format refers to the weight serialization, or clarify that "packaging.format" refers strictly to the container packaging layout.

danieloh30 · 2026-09-24T06:16:08Z

+| `org.opencontainers.image.created` | Creation timestamp. |
+| `org.opencontainers.image.licenses` | License identifier(s). |
+
+## Open questions


We may need to add "TAG DevEx Position" for each open question, if possible.

For example, question #2:

TAG DevEx Position: Keep OpenPubkey out of the required enum for v1, but allow sigstore, notation, and an extensible string format or other value. Sigstore already encompasses keyless identity via OIDC/Fulcio, which covers most zero-trust developer use cases without overcomplicating v1 verification logic in local runtimes.

danieloh30

Looks great to me. Added a few minor suggestions!

Add draft OCI annotation conventions for interoperability profile

87058a7

Signed-off-by: Savitha Raghunathan <saveetha13@gmail.com>

savitharaghunathan requested a review from a team as a code owner September 10, 2026 12:55

github-actions Bot requested review from SwEngin, danieloh30 and graz-dev September 10, 2026 12:55

caldeirav reviewed Sep 11, 2026

View reviewed changes

Incorporate MOF component vocabulary from review feedback

9fa8c6b

Signed-off-by: Savitha Raghunathan <saveetha13@gmail.com>

kdubois approved these changes Sep 18, 2026

View reviewed changes

sabre1041 reviewed Sep 21, 2026

View reviewed changes

savitharaghunathan added 2 commits September 21, 2026 09:59

Address reviewer feedback on annotations spec

735ea22

Signed-off-by: Savitha Raghunathan <saveetha13@gmail.com>

Merge description and evidence columns for table readability

5b94196

Signed-off-by: Savitha Raghunathan <saveetha13@gmail.com>

brandtkeller requested review from caldeirav and sabre1041 September 23, 2026 16:34

danieloh30 reviewed Sep 24, 2026

View reviewed changes

github-project-automation Bot added this to TAG Developer Experience, TAG Infrastructure and TAG Security and Compliance Sep 24, 2026

github-project-automation Bot added this to TAG Workloads Foundation, CNCF TOC Board and TAG Operational Resilience Sep 24, 2026

	4. Worked example — this table should get run through a full example manifest end to end
	4. Reference Implementation — this table should get run through a full example manifest end to end

Conversation

savitharaghunathan commented Sep 10, 2026

Uh oh!

caldeirav left a comment

Choose a reason for hiding this comment

Uh oh!

savitharaghunathan commented Sep 17, 2026

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sabre1041 commented Sep 20, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

savitharaghunathan commented Sep 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

danieloh30 left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

savitharaghunathan commented Sep 21, 2026 •

edited

Loading