How to handle multiple manifests with the same ref.name

[zhouhao3]

When the implementation of create or unpack, if according to the input ref, in the index.json can be found in a number of correspondence, this situation should be how to deal with? Is it supposed to handle all? Or deal with one? I was wondering if it should be added in the specification to increase the limit on org.opencontainers.ref.name?
cc/@opencontainers/image-tools-maintainers

[vbatts]

they are regarded like an image tag, and therefore should be unique. Though there might be a situation where multiples are valid i.e. same name for different architectures, or some other distinguishing attribute.

[zhouhao3]

 {
    "schemaVersion": 2,
    "manifests": [
      {
        "mediaType": "application/vnd.oci.image.index.v1+json",
        "size": 659,
        "digest": "sha256:c0b331a7636358cb4cca3a453eeb88554dc679290b27b8f5fad53322dddc36bf",
        "annotations": {
          "org.opencontainers.ref.name": "v1.0"
        }
      },
      {
        "mediaType": "application/vnd.oci.image.manifest.v1+json",
        "size": 622,
        "digest": "sha256:cd4c216fcb2ce4f1e1c18f2d53dd5a00f72b27ae21eaccafabe4c00b86e9326e",
        "platform": {
          "architecture": "ppc64le",
          "os": "linux"
        },
        "annotations": {
          "org.opencontainers.ref.name": "v1.0"
        }
      }
    ],
    "annotations": {
      "com.example.index.revision": "r124356"
    }
}

In this index.json example, when the input ref value is v1.0, the current method is to find only the first matching ref.name to return.

Is this example not allowed to exist? If that is the case, we should add a unique validation to ref.name, if not, do we only deal with the first one correctly?

[stevvooe]

@q384566678 These are two different images, with the same ref. The UI needs to take this into account. The unique item here is the digest, not the ref. Imagine if this were an annotation unrelated to OCI and you wanted to expose a selection based on that annotation. Also, imagine the case where the index is assembled from two separate sources that may disagree on the ref. From a UX perspective, the user should be able to disambiguate these cases.

[zhouhao3]

@stevvooe So the best basis for the search is not ref.name but digest? But if it is digest search, the user is very troublesome to enter, and even some do not know digest.
I think we'd better add a required and unique attribute to ref.name, or listReferences is not comprehensive according to ref.name (ref.name does not exist in index.json).If not, I would like to replace the ref. name with digest name to perform listReferences.

[stevvooe]

@q384566678 What if I have another attribute foo that I want to select an image on? How will that be handled? Should we enforce uniqueness on that annotation, as well?

The problem with requiring ref to be unique is that it kicks this problem down the road for all other annotations. It becomes a special annotation, which is not the goal.

As far as listReferences goes, it makes the assumption that descriptors in a manifest are unique along some attribute, which is not guaranteed. It should probably return map[string][]v1.Descriptor or just a list. Provide helper methods that can match items in a list of descriptors:

descs := listReferences(index)

// select all descs with ref foo
descs = selectDescs(descs, "annotations.org.opencontainers.ref.name==foo")

// select all descs that are from the linux platform
descs = selectDescs(descs, "platform.os==linux")

// select all descs with a specific digest
descs = selectDescs(descs, "digest==sha256:...")

By supporting image selection along a number of attributes, we can support a much wider range of use cases and ensure that they are handled broadly.

[zhouhao3]

@stevvooe If it is to allow users to enter the search content, or may have multiple results, which in return to our initial question, how to deal with multiple results?
I have a few thoughts on this question:

1. If you get more than one result, continue to enter the search condition until you get a result.
2. Handle multiple results, like the validate function (this should not work because it can not be executed in a non-empty folder)
3. Retrieve only the contents of the unique attribute（digest）, but the input is a bit cumbersome.

[zhouhao3]

@vbatts @stevvooe @xiekeyang @coolljt0725 @jonboulle @wking Do you have any suggestions?

[stevvooe]

@q384566678 The above comment is a suggestion. Selecting items from a list isn't wildly complicated. In the vast number of cases, only a single result is returned:

descs = selectDescs(descs, criteria...)
if len(descs) > 1  {
  return fmt.Errorf("not unique") // list out result in this case.
} else if len(descs) == 0 {
  return fmt.Errorf("no match")
}

desc := descs[0]

The other approach is to simply take the first match:

descs = selectDescs(descs, criteria...)
if len(descs) == 0 {
  return fmt.Errorf("no match")
}

desc := descs[0]

Limiting uniqueness over an arbitrary annotation is simply not an option. Do so will prevent future use cases of image indexes to be useful.

[zhouhao3]

@stevvooe thanks for your advice, I make #169 to solve the problem. PTAL.