Should we delete this repository?

[jonjohnsonjr]

The guidance here is more harmful than if it simply didn't exist.

Encouraging the proliferation of custom mediaTypes (rather than reusing existing, registered types) reduces the ability to reuse software. If your layers are gzipped tarballs, there's no reasons to invent a unique layer media type.

There's no reason to prescribe an opinionated framework on top of RFC 6838. This guidance just obscures what artifact authors should be looking at.

[vrothberg]

The guidance here is more harmful than if it simply didn't exist.

What should folks do if they have a legitimate need for creating a new artifact? I am a bit puzzled by the issue title.

Encouraging the proliferation of custom mediaTypes (rather than reusing existing, registered types) reduces the ability to reuse software. If your layers are gzipped tarballs, there's no reasons to invent a unique layer media type.

I totally agree. Existing media types should be reused whenever possible.

[Toasterson]

There is legitimate reason to extend with new artifact types, For example new file formats like qcow, zfs streams (compressed, uncompressed) which at the moment use completely different software bases could now leverage the registry infrastructure being provided by registry providers. So for the reason of making software more reusable i think this repo should exist to guide the inclusion in the future.

[mikebrow]

We should probably delete this repository

Is that guidance from opencontainers/wg-reference-types? I was expecting to see use cases, prototypes built on the wg proposal, for explaining how such custom artifacts should be implemented. Is that part of the workgroup being deleted?

The guidance here is more harmful than if it simply didn't exist.

We plan, on updating guidance based on the wg. output when it arrives and/or if it is accepted by the specs.

We will probably include a map/migration between proposal A and E, for those that engaged early in the year(s) before proposal E existed.

Encouraging the proliferation of custom mediaTypes (rather than reusing existing, registered types) reduces the ability to reuse software. If your layers are gzipped tarballs, there's no reasons to invent a unique layer media type.

ok?

vrothburg: I totally agree. Existing media types should be reused whenever possible.

100% agree, whenever possible, and not at all cost.

Jamming everything typed that doesn't fit your one artifact type to rule them all.. into a list of name value pairs (annotations),.. Seems patchy, no?

[imjasonh]

My 2c as a non-TOB person, only as a community and WG contributor / meeting attendee / opinion haver: the reference WG does not have the definition of new types of things in its scope and charter, only how things can reference other things. Expanding that WG's scope to include how types of things are expressed and how new types are defined/proposed/specified seems like a distraction, when it's actually finally making progress toward its actual purpose.

Maybe there's room for a "new types WG" but that should be a separate from the references WG (hopefully after, for my meeting attendance tolerance 😅).

In any case, I agree with Jon that the existence of this repo as a non-spec promoted alongside the real specs, ambiguously worded so that it seems more official than it is, is harmful to readers who may not be familiar with its positioning. Luring unaware new users into adhering to this non-spec instead of the already-widely-adopted RFC 6838 will cause problems later if we ever want to make changes to it (including perhaps while making it a real spec!). Based on the discussion in #56 this ambiguity seems to be intentional, or at least not well understood by this repo's maintainers.

[mikebrow]

My 2c as a non-TOB person, only as a community and WG contributor / meeting attendee / opinion haver: the reference WG does not have the definition of new types of things in its scope and charter, only how things can reference other things. Expanding that WG's scope to include how types of things are expressed and how new types are defined/proposed/specified seems like a distraction, when it's actually finally making progress toward its actual purpose.

I might be reading it wrong... or it might be outdated? new artifacts type right here: https://github.com/opencontainers/wg-reference-types/blob/main/docs/proposals/PROPOSAL_E.md#artifact-spec and note the new custom types being proposed as annotations just below.

Maybe there's room for a "new types WG" but that should be a separate from the references WG (hopefully after, for my meeting attendance tolerance 😅).

:-)

In any case, I agree with Jon that the existence of this repo as a non-spec promoted alongside the real specs, ambiguously worded so that it seems more official than it is, is harmful to readers who may not be familiar with its positioning. Luring unaware new users into adhering to this non-spec instead of the already-widely-adopted RFC 6838 will cause problems later if we ever want to make changes to it (including perhaps while making it a real spec!). Based on the discussion in #56 this ambiguity seems to be intentional, or at least not well understood by this repo's maintainers.

There are a "plethora" of references, in this repository to rfc 6838 and the iana process.

I only notice one current error wrt. custom types, that was not an error at the time of it's writing. I believe the image spec changed.. to forbid custom types, correct? I only found that change in the image spec last week after the OCI call, at the mention of custom types not being supported.

ambiguous? The very first paragraphs of the reference the OP cited starts out with a direct quote of the tob approved project scope:

More particularly, this repository has been [tasked by the OCI TOB to serve 3 primary goals](https://github.com/opencontainers/tob/blob/master/proposals/artifacts.md):

Artifact Authors - guidance for authoring new artifact types, including a clearing house for [well known](https://github.com/opencontainers/artifacts/blob/main/definitions-terms.md#well-known-type) artifact types.
Registry Operators and Vendors - guidance for how operators and vendors can support new artifact types, including how they can opt-in or out of well known artifact types. Registry operators that already implement mediaType filtering will not have to change. The artifact repo will provide context on how new mediaTypes can be used, and how mediaTypes can be associated with a type of artifact.
Clearing House for [Well-known Artifacts](https://github.com/opencontainers/artifacts/blob/main/definitions-terms.md#well-known-type) - artifact authors can submit their artifact definitions, providing registry operators a list by which they can easily support.

[sudo-bmitch]

We will probably include a map/migration between proposal A and E, for those that engaged early in the year(s) before proposal E existed.

I think migration from anything groups have done separate from the OCI specs to whatever the WG proposes should be left up to those groups to implement themselves. It's not just proposal A, there's also proposal B, and there's no way to know what other things have been created separate from our work here.

If OCI had previously recommended a way to refer from one artifact to another, and we were changing that, then I'd expect us to create a migration plan for that scenario.

[imjasonh]

I might be reading it wrong... or it might be outdated? new artifacts type right here: https://github.com/opencontainers/wg-reference-types/blob/main/docs/proposals/PROPOSAL_E.md#artifact-spec and note the new custom types being proposed as annotations just below.

As I understand it, the WG is proposing a single new media type for a non-image-non-index manifest, and not trying to become a catalog of arbitrary new types.

Or, I might also be reading it wrong or have an outdated view. 🙃

ambiguous? The very first paragraphs of the reference the OP cited starts out with a direct quote of the tob approved project scope:

More particularly, this repository has been [tasked by the OCI TOB to serve 3 primary goals](https://github.com/opencontainers/tob/blob/master/proposals/artifacts.md):

Artifact Authors - guidance for authoring new artifact types, including a clearing house for [well known](https://github.com/opencontainers/artifacts/blob/main/definitions-terms.md#well-known-type) artifact types.
Registry Operators and Vendors - guidance for how operators and vendors can support new artifact types, including how they can opt-in or out of well known artifact types. Registry operators that already implement mediaType filtering will not have to change. The artifact repo will provide context on how new mediaTypes can be used, and how mediaTypes can be associated with a type of artifact.
Clearing House for [Well-known Artifacts](https://github.com/opencontainers/artifacts/blob/main/definitions-ter

Maybe my issue is with the space between a "spec" and just "guidance". The guidance available here hasn't been written with the same level of multi-stakeholder review and rigor as the actual specs, yet it's often referred to as equivalent in terms of authoritativeness.

The whole of this repo could boil down to "put whatever you want in .config.mediaType; vnd.oci is a reserved prefix", and not be a separate spec at all.

IMO there doesn't need to be a concept of well-known artifact types at all, or a clearing house for them. Having a process to become "well-known" is a barrier to adoption and leads to folks reusing/abusing "well-known" types, like they've reused/abused the standard OCI media types.

Wordy guidance about how to construct a new media type should just link to existing more authoritative guidance from IANA and RFC 6838.

I would also drop this section on Visualizing Artifacts, since it seems to be trying to build some authoritative mapping of mediaType strings to icons, which AFAIK nobody in practice adheres to.

I might go a step back from deleting this repo entirely, and say that it could use a heavy edit, and a rename to something like "artifacts-guidance", then live on as guidance for artifact authors and registry implementations according to (2/3rds of) the project's charter. That guidance is effectively, "put whatever you want in .config.mediaType; vnd.oci is a reserved prefix", which fits on a large postage stamp if you write small.

[mikebrow]

We will probably include a map/migration between proposal A and E, for those that engaged early in the year(s) before proposal E existed.

I think migration from anything groups have done separate from the OCI specs to whatever the WG proposes should be left up to those groups to implement themselves. It's not just proposal A, there's also proposal B, and there's no way to know what other things have been created separate from our work here.

If OCI had previously recommended a way to refer from one artifact to another, and we were changing that, then I'd expect us to create a migration plan for that scenario.

I understand the point... and I see some evidence this area (artifacts) is still undergoing innovation and debate.

OCI charter mission statement cite from:

1. Mission of the Open Container Initiative (“OCI”).

The Open Container Initiative provides an open source technical community
within which industry participants may easily contribute to building
vendor-neutral, portable and open specifications, reference implementations,
and tools that deliver on the promise of containers as a source of application
portability backed by a certification program.

The Open Container Initiative does not seek to be a marketing organization,
define a full stack or solution requirements, and will strive to avoid
standardizing technical areas undergoing innovation and debate.

[sudo-bmitch]

See also opencontainers/wg-reference-types#62 where we may want to merge some of the advice here with the schemas being proposed. When that's done, it may make sense to archive this repo to avoid confusion. But this is very forward looking based on things that would need to be approved by lots of people.

[mikebrow]

See also opencontainers/wg-reference-types#62 where we may want to merge some of the advice here with the schemas being proposed. When that's done, it may make sense to archive this repo to avoid confusion. But this is very forward looking based on things that would need to be approved by lots of people.

true it may .. lots of dominos left to fall

[mikebrow]

As I understand it, the WG is proposing a single new media type for a non-image-non-index manifest, and not trying to become a catalog of arbitrary new types.

new artifact type with refers that has "mediaType": "application/vnd.oci.image.manifest.v1+json", // any manifest media type , and adding refers to image, and adding annotation definition org.opencontainers.artifact.type: type of artifact (sig, sbom, etc)

I see use cases :-)

Maybe my issue is with the space between a "spec" and just "guidance". The guidance available here hasn't been written with the same level of multi-stakeholder review and rigor as the actual specs, yet it's often referred to as equivalent in terms of authoritativeness.

fair.. from my view the effort to apply rigor ended up with a request to the tob for a wg with the authority to provide acceptable changes to the existing specs and other things we felt nec. to bring in said multi-stakeholder review and rigor.

I might go a step back from deleting this repo entirely, and say that it could use a heavy edit, and a rename to something like "artifacts-guidance",

rename: naming is hard..
heavy edit: yes

then live on as guidance for artifact authors and registry implementations according to (2/3rds of) the project's charter. That guidance is effectively, "put whatever you want in .config.mediaType; vnd.oci is a reserved prefix", which fits on a large postage stamp if you write small.

Maybe somewhere between War and Peach and a postage stamp?

[afflom]

What are the implications of the proposed repo deletion on projects/technologies currently leveraging OCI as general content storage?

[rchincha]

Clarification (1)?

See that only "vnd.oci.image.manifest.v1+json" has been registered as a IANA media-type [1], while these media-types [3] have been defined in the OCI image spec [3].

Also, as per RFC 6838 wrt vendor trees [2], as it reads, "OCI" is positioned as a industry consortium which does not "qualify as recognized standards-related organization" and hence whatever media-types it comes up get stuffed under vnd.oci.* and further updates don't quite require IANA intervention or arbitration until someone else proposes adding "application/vnd.oci.layout.header.v1+json" without OCI knowledge.

Clarification (2)?

Assuming artifacts and registries are inseparable, should "intelligence" be moved into a registry meaning should the registry become content-aware? Or should the intelligence remain at the client-side (push and pull)? If the former, then some way to select on the content? Either media-type or annotations?

Clarification (3)?

Registries have common use cases, which coincidentally also require registries to become content-aware - security scans, garbage collection, etc. Should there be a one-to-one correspondence between a well-defined media-type (hence "standards") for each use case instead of many different media-types ("proprietary") for the same use case?

"A registry will guarantee GC and referential integrity iff you conform to media-type X"
(vs)
"A registry will guarantee GC and referential integrity if media-type X is one of many supported"

References:

[1] https://www.iana.org/assignments/media-types/media-types.xhtml
[2] https://datatracker.ietf.org/doc/html/rfc6838#section-3.2
[3] https://github.com/opencontainers/image-spec/blob/main/media-types.md

[rchincha]

@jonjohnsonjr, could you also expand on this a bit?

This guidance just obscures what artifact authors should be looking at.

[jonjohnsonjr]

$ crane manifest radumatei/components-oci:20 | jq 
{
  "config": {
    "digest": "sha256:e89acb10dee2fec22203f25b734510940419d8f3e4a292ed3d4d104e614551f4",
    "mediaType": "application/vnd.wasm.config.v1+json",
    "size": 331
  },
  "layers": [
    {
      "annotations": {
        "org.opencontainers.image.title": "my-component"
      },
      "digest": "sha256:db7ca53ddfc81dc58032553ce90859e2ed2fe458febc84536a894585bfb59b1f",
      "mediaType": "application/vnd.wasm.content.layer.v1+wasm",
      "size": 2087464
    },
    {
      "digest": "sha256:8c69a84ec5adec97e47d4250410a7689046762aaa8e89f82ddbb4a89acb7388e",
      "mediaType": "application/vnd.wasm.content.layer.v1+data",
      "size": 96
    },
    {
      "digest": "sha256:2e5ac59e65b6c3dfe0b322c80215cd6f18c28818053ad876ec4760dfe3527dc5",
      "mediaType": "application/vnd.wasm.content.layer.v1+data",
      "size": 404
    }
  ],
  "schemaVersion": 2
}

😭

[SteveLasker]

Closing as the evolution of OCI Artifacts is being covered as a TOB Vote: opencontainers/tob#126