Registering media types for OCI Artifacts
Steve Lasker
Just a heads up. As part of the Artifacts work, we discussed using IANA for registering the mediaTypes.
It turns out we don’t actually have any of the oci-image spec mediaTypes registered.
To test out the IANA registration process, I’m going to submit:
- vnd.oci.image
- vnd.oci.layer
As part of the registration, I need to provide a contact and email. I was going to use the t...@opencontainers.org to be future proof-ish. So, just in case you see emails coming back, this is why.
Aleksa Sarai
> Just a heads up. As part of the Artifacts work, we discussed using IANA for registering the mediaTypes.
Sure, that was intentional -- "vnd." mediaTypes don't need to be
> To test out the IANA registration process, I'm going to submit:
> * vnd.oci.layer
If we're going to register them (which I think is a good idea), there
should probably at least be a discussion about what they should look
like before you send a request to register them. Maybe this discussion
has happened elsewhere and I wasn't aware of it, but just from the
outset there area few things that I think should be considered:
* If we're registering them with IANA we don't need to put them in the
vendor tree. Since OCI is a standards organisation (as per the
definition in RFC 6838) we can just use "oci." (or possibly
"opencontainers.") as the top-level name.
* Presumably you are going to register these under the application/
type?
* How are we going to deal with versioning? Right now we mis-use the
subtype name but looking at RFC 6838 the correct way would be with
MIME-type parameters. For instance, a "v" or "version" parameter
could be used to specify the spec version.
* To me, vnd.oci.image is ambiguous -- which part of an OCI image is it
referring to?
* Also, vnd.oci.layer is a bit strange -- what is an "OCI layer"? The
OCI spec currently uses "vnd.oci.image.layer" followed by some other
things. Also we'd need to have an optional parameter to specify if
layers are non-distributable.
> As part of the registration, I need to provide a contact and email. I
> was going to use the
--
Aleksa Sarai
Senior Software Engineer (Containers)
SUSE Linux GmbH
<https://www.cyphar.com/>
Steve Lasker
Hey Aleksa,
Great questions, and there’s a bunch of info here to put the full context.
This was all part of the Artifacts work. Here’s a clean view of the Artifacts spec PR. Most of the meeting notes are in weekly OCI meeting notes: https://hackmd.io/El8Dd2xrTlCaCG59ns5cwg
Below are some of the notes that talked about where we debated the mediaTypes, the uniqueness and the format. The written notes didn’t capture all of the conversations, and we weren’t doing recordings back then.
OCI Meeting Notes:
mediaTypes
· Jon provided more details to the RFC for mediaTypes. Steve promises to read the full RFC, so Jon doesn’t have to keep ansewring the same question. Steve to put enough context in the artifacts spec, but point to the RFC for details so we don’t reinvent what’s already there.
· Artifacts will move forward with the following approach
o the uniqueness of an artifact will be the left portion of the config.manifest.mediaType, up to, but not including the +
o application/vnd.oci.image.config.v1 = the uniqueness the +json provides the encoding of the config.
The outcomes were:
- We need a place to register unique types, to avoid the Artifact maintainers from being a clearing house of names for new well-known Artifact names. For instance, how does Helm, Singularity and OPA get ownership of their mediaType names? Iana already does this, so we felt that was the right place. I had the todo to follow up. With the holidays, Notary v2 work, this was my followup actions.
- We realized we never registered the vnd.oci.* mediaTypes and it was a good place to start.
- The mediaTypes could be a bit cleaner, including how the suffix is used, and how layers, blobs and ordinal lists mean something for container images. But, we didn’t want to destabilize the current implementations that already use oci-image spec mediaTypes
IANA Registrations
Reading RFC 6838, there’s various sections on registering types:
A registration process is needed for these labels, so that the set of
such values are defined in a reasonably orderly, well-specified, and
public manner.
This document specifies the criteria for media type registrations and
defines the procedures to be used to register media types (Section 5)
as well as media type structured suffixes (Section 6) in the Internet
Assigned Numbers Authority (IANA) central registry.
The location of the media type registry managed by these procedures
is:
http://www.iana.org/assignments/media-types/
3.2. Vendor Tree
The vendor tree is used for media types associated with publicly
available products. "Vendor" and "producer" are construed very
broadly in this context and are considered equivalent. Note that
industry consortia as well as non-commercial entities that do not
qualify as recognized standards-related organizations can quite
appropriately register media types in the vendor tree.
While it would be great to wind back, and possibly use oci as the root, is this really something we want to take on at this point?
Versioning
Another great topic. For now, we are using part of the mediaType as the version: application/vnd.oci.image.manifest.v1+json
In the artifacts spec, the versioning is called out as required: Defining a Unique Artifact Type and versioning
This is another place we could probably do better, but do we really want to unwind the work and clients that have already implemented the OCI spec?
vnd.oci.image
“* To me, vnd.oci.image is ambiguous -- which part of an OCI image is it referring to?”
I think you’re referring to what does oci.image mean? This was the source of the other thread we were discussing on things that can push/pull from a distribution instance. For the Artifacts Spec, the section: Defining a Unique Artifact Type references oci.image as this:
Note: The config.mediaType of application/vnd.oci.image.config.v1+json is
reserved for artifacts intended to be instanced by docker, containerd and
other OCI Image toolchains.
vnd.oci.layer
* Also, vnd.oci.layer is a bit strange -- what is an "OCI layer"? The
OCI spec currently uses "vnd.oci.image.layer" followed by some other
things. Also we'd need to have an optional parameter to specify if
layers are non-distributable.
Just a quick typo. It should be vnd.oci.image.layer. To test the submission process, I’ve only submitted vnd.oci.image. I was going to email the Iana “experts” group and get their feedback.
The ultimate goal here isn’t really about registering oci.image or oci.image.layer, rather to test the process for how new Artifact authors submit their type registrations. In the spec, I plan to call out this process. So, I really need to test it before I put it in the spec.
Happy to chat 1:1 to catch up on all this work and get your input.
Steve
It turns out we don’t actually have any of the oci-image spec mediaTypes registered.
To test out the IANA registration process, I’m going to submit:
- vnd.oci.image
- vnd.oci.layer
As part of the registration, I need to provide a contact and email. I was going to use the t...@opencontainers.org to be future proof-ish. So, just in case you see emails coming back, this is why.