Question about OCI Index Template

[xiekeyang]

Here 1 declare that server provides discovered OCI index object which entry should conform to application/vnd.oci.image.manifest.v1+json. However in example casEngines entry 2 doesn't belong to OCI index 3. We can't parse the object according to current image-spec 4. How about to change the casEngine definition to annotations, to conform to OCI index strictly, like:

{
  "schemaVersion": 2,
  "manifests": [
    {   
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "size": 799,
      "digest": "sha256:e9770a03fbdccdd4632895151a93f9af58bbe2c91fdfaaf73160648d250e6ec3",
      "platform": {
        "architecture": "ppc64le",
        "os": "linux"
      },  
      "annotations": {
        "org.opencontainers.image.ref.name": "1.0",
        "org.opencontainers.cas.protocol": "oci-cas-template-v1",
        "org.opencontainers.cas.uri": "https://example.com/oci-cas/{algorithm}/{encoded:2}/{encoded}"
      }
    }   
  ]
}

There is a problem: according to casEngines, it should be array type, but my example allows only one pair of protocol to uri. I think we can resolve this by extending annotations words to allow many pairs. IMO, I feel only one pair of protocol and uri might be enough. Is there any possible of many uris for one protocol?

[wking]

However in example casEngines entry 2 doesn't belong to OCI index...

Image-spec doesn't seem to have an analog to runtime-spec's extensibility section. But the presence of reserved properties suggests similar intentions. So I think adding a casEngines extention is legal, although having clearer extention wording in image-spec would be nice.

However, my plan is to get casEngines, the CAS-protocol registry, and the OCI CAS-Template Protocol upstreamed into image-spec. I think the're useful (like urls) regardless of discovery protocols. casEngines only needs to be an extention until then.

We can't parse the object according to current image-spec...

Sure you can. It's unfortunate that the current image-spec Go types and image-tools functions don't provide for extention properties, but a workaround is to hold the casEngines entries locally, call the image-* tooling to pick out the matching descriptors, and the re-associate the casEngine data with the matched descriptors.

Alternatively, you could skip image-tools and just reproduce the descriptor-matching locally in a way that preserves extention data.

I think we can resolve this by extending annotations words to allow many pairs.

I'd have preferred annotations values be opaque. But I am not in favor of repeat keys. On that, RFC 7159 says:

An object whose names are all unique is interoperable in the sense that all software implementations receiving that object will agree on the name-value mappings. When the names within an object are not unique, the behavior of software that receives such an object is unpredictable. Many implementations report the last name/value pair only. Other implementations report an error or fail to parse the object, and some implementations report all of the name/value pairs, including duplicates.

So I think the best approach now is an extention property which we attempt to upstream.

IMO, I feel only one pair of protocol and uri might be enough. Is there any possible of many uris for one protocol?

Sure. When publishing, you canmake more people happy by pushing to more places. For example, maybe some consumers prefer Docker's CAS protocol, while others prefer OCI CAS-templates. Push to both, set them in casEngines, and make both happy.

[wking]

...but a workaround is to hold the casEngines entries locally, call the image-* tooling to pick out the matching descriptors, and the re-associate the casEngine data with the matched descriptors.

One way to do this is to create an extended descriptor struct that also supports casEngines and an extended image struct that uses the extended descriptor struct. Parse the image Json into the extended image struct. Iterate over manifests and for any casEngines, pack them into annotations as serialized JSON:

descriptor.Annotations["org.opencontainers.discover.casEngines"] = WhateverGosJSONSerializerIs(descriptor.CasEngines)

And then unpack back into casEngines on the other side.

We could use an annotation like that in the spec instead of tje casEngines property, but my current impression is that the extention issue is a shortcoming we can fix in the upstream Go.

[wking]

Alternatively, you could skip image-tools and just reproduce the descriptor-matching locally in a way that preserves extention data.

This is the way I went with in #23, with the hope being that casEngines is upstreamed into image-spec in the next year or two ;). The current name matching is pretty simple, so it's not much to carry locally, although we'll likely have similar issues in any platform-matching code.