OCI announces upcoming changes for registries

The Open Container Initiative (OCI) has recently announced a list of major registry changes you can expect to see soon in their blog post “Summary of Upcoming Changes in OCI Image and Distribution Specs v1.1.”

‍

Several of us here at Chainguard have been involved in these efforts and are excited to see them materialize. We have written a bit more on this topic in previous posts here and here.

‍

After about a year and half, it seems that OCI is ready to finally deliver new spec versions which enable the ability to create and discover relationships between objects in a registry.In this post we will briefly reiterate the major changes you can expect to see in the upcoming OCI image and Distribution specs v1.1.

‍

The “OCI Artifact” becomes ratified

‍

On Chainguard Academy, we have a page titled “What are OCI artifacts?". On that page, we cover the confusion with the term “OCI Artifact” (capital “A” vs. lowercase “a”). In short, “OCI Artifact” refers to the historical usage of the config.mediaType field to denote an alternative (non-container) artifact stored in a registry. This is the method used by early adopters such as the Helm project.

‍

Here’s an example of an “OCI Artifact” image manifest representing a Helm chart (note the custom value for config.mediaType:

{
  "schemaVersion": 2,
  "config": {
    "mediaType": "application/vnd.cncf.helm.config.v1+json",
    "digest": "sha256:8ec7c0...",
    "size": 117
  },

...

In the upcoming spec releases, a new field named artifactType can be set on an image manifest as a first-class mechanism to define an OCI Artifact. If the artifactType field is missing, config.mediaType will be respected as an official fallback/legacy mechanism for determining the artifact type.

‍

For more specifics on this topic, please see OCI’s new Guidelines for Artifact Usage.

‍

Manifests can now reference other objects

‍

A new field (nested JSON object) has been added on the image manifest called subject which allows you to point to another object which has already been published to the registry:

{
...
  "subject": {
    "mediaType": "application/vnd.oci.image.manifest.v1+json",
    "digest": "sha256:5b0bca...",
    "size": 7682
  },
...
}

As not all registries will support this functionality on day 1, the registry is required to return an OCI-Subject header containing the value of subject.digest. This allows clients to determine whether the subject has been processed and that this relationship has been processed server-side.

‍‍

API endpoint added for discovering related objects

‍

Since the ability has been added to create relationships via the new subject field, a new endpoint has been added to the registry API to query/discover them as well:

GET /v2/<name>/referrers/<digest>

This will return a list of objects which have been published to the registry with a subject.digest matching the value of <digest> provided in the request URL:

{
  "schemaVersion": 2,
  "mediaType": "application/vnd.oci.image.index.v1+json",
  "manifests": [
    {
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "size": 1234,
      "digest": "sha256:a1a1a1...",
      "artifactType": "application/vnd.example.sbom.v1",
      "annotations": {
        "org.opencontainers.artifact.created": "2022-01-01T14:42:55Z",
        "org.example.sbom.format": "json"
      }
    },
    {
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "size": 1234,
      "digest": "sha256:a2a2a2...",
      "artifactType": "application/vnd.example.signature.v1",
      "annotations": {
        "org.opencontainers.artifact.created": "2022-01-01T07:21:33Z",
        "org.example.signature.fingerprint": "abcd"
      }
    }
  ]
}

If the JSON body above seems familiar, it's because the schema of the HTTP response to this endpoint is a valid OCI Image Index. This was done on purpose since most clients already know how to parse this type.

‍

Notice the artifactType included in each of the descriptors in the manifest list above. This maps to either the top-level artifactType on the published manifest, or, if this new field is missing, the value of the legacy artifact indicator config.mediaType as described earlier.

‍

This endpoint will also return a Link header (RFC5988) if there is another page of results for the client to retrieve.

‍

Lastly, this endpoint supports filtering by artifactType (e.g. “give me all the SBOMs”). This is done by supplying a querystring in the form ?artifactType=<mediaType>. A registry may or may not support this server-side filtering mechanism. However, if filtering is supported, the registry must respond with a header OCI-Filters-Applied: artifactType indicating that the response has been filtered.