PROPOSAL_B.md

Proposal B

Add "reference" field to existing schemas

Description

The following proposal describes adding a new field to the existing JSON schemas to enable the creation of relationships between objects stored in an OCI registry.

Additionally it describes a new read-only endpoint on the registry HTTP API to allow listing of all objects which reference a given object.

Links

Description	Link
Original proposal (image-spec)	View
PR to implement (image-spec)	View
Fork of distribution with support	View
Diagram of usage pattern	View

Modifications

JSON Schema

All existing supported JSON schemas (index/manifest/descriptor) will be allowed to include a new field, reference, which is itself a descriptor object:

{
  "mediaType": "application/vnd.oci.image.manifest.v1+json",
  "size": 2345,
  "digest": "sha256:b2b2b2...",
  "reference": { // new field
    "mediaType": "application/vnd.oci.image.manifest.v1+json", // any manifest media type
    "size": 1234,
    "digest": "sha256:a1a1a1..."
  }
}

Registry HTTP API

A single, read-only endpoint will be added to the registry HTTP API:

GET /v2/<name>/manifests/<ref>/references

The response will be a valid index, containing a manifests array, which is the complete list of descriptor objects referencing a given <ref> (tag or digest) on a given <name> (repo).

For example:

GET /v2/products/cones/manifests/neapolitan/references

{
  "schemaVersion": 2,
  "mediaType": "application/vnd.oci.image.index.v1+json",
  "manifests": [
    {
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "size": 2345,
      "digest": "sha256:b2b2b2..."
    },
    {
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "size": 2345,
      "digest": "sha256:c3c3c3..."
    },
    {
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "size": 2345,
      "digest": "sha256:d4d4d4..."
    }
  ],
  "annotations": [
    // reserved for future use
  ]
}