Defines a new artifact manifest and corresponding referrers extension API.
Provides a new manifest type, with an optional subject
reference to another manifest (runtime image), an artifactType
to differentiate types of artifacts (signatures, sboms, security scan results) and renames layers
to optional blobs
.
The modifications include:
Description | Link |
---|---|
GitHub issue where this was first proposed: | OCI Artifact Manifest - with weak reference support #27 OCI Artifact Manifest, Phase 1-Reference Types #29 |
Current ORAS Specifications: | Manifest and Referrers API |
Implementations | Registry: ORAS Fork of CNCF Distribution (WIP) Registry: ZOT Project (merged) Registry client: oras-project/oras/tree/artifacts |
The Artifact manifest is similar to the OCI image manifest, but removes constraints defined on the image-manifest such as a required config
object and required & ordinal layers
.
It adds a subject
property supporting a graph of independently linked artifacts.
The addition of a new manifest does not change, nor impact the image.manifest
.
It provides a means to define a wide range of artifacts, including a chain of related artifacts enabling SBoMs, signatures and metadata that can be related to an image.manifest
, image.index
or another artifact.manifest
.
By defining a new manifest, registries and clients opt-into new capabilities, without breaking existing registry and client behavior or setting expectations for scenarios to function when the client and/or registry may not yet implement new capabilities.
An Artifact manifest, representing a detached signature of the hello-world@sha256:abc123
image:
- The signature is stored as a
blob
- The signature points to the
hello-world@sha256:abc123
image through thesubject
property - Sorting of references may be achieved by setting a
created
annotation.
{
"mediaType": "application/vnd.oci.artifact.manifest.v1+json",
"artifactType": "signature/example",
"blobs": [
{
"mediaType": "application/tar",
"digest": "sha256:def456",
"size": 32654
}
],
"subject": {
"mediaType": "application/vnd.oci.image.manifest.v1+json",
"digest": "sha256:abc123",
"size": 16724
},
"annotations": {
"org.opencontainers.artifact.created": "<createdDate>"
}
}
-
mediaType
stringThis field contains the
mediaType
of this document, differentiating from image-manifest and image-index. ThemediaType
for this manifest type MUST beapplication/vnd.oci.artifact.manifest.v1+json
, where the version WILL change to reflect newer versions. -
artifactType
stringThe REQUIRED
artifactType
is a unique value, as registered with iana.org. Examples includesignature/example
,sbom/example
,ice-cream/example
. For details on creating a uniqueartifactType
, see OCI Artifact Authors Guidance -
blobs
array of objectsAn OPTIONAL collection of 0 or more blobs. The blobs array is analogous to oci.image.manifest layers, however unlike image-manifest, the ordering of blobs is specific to the artifact type. Some artifacts may choose an overlay of files, while other artifact types may store independent collections of files.
- Each item in the array MUST be an artifact descriptor, and MUST NOT refer to another
manifest
providing dependency closure. - The max number of blobs is not defined, but MAY be limited by distribution-spec implementations.
- Each item in the array MUST be an artifact descriptor, and MUST NOT refer to another
-
subject
descriptorAn OPTIONAL reference to any existing manifest within the repository. When specified, the artifact is said to be dependent upon the referenced
subject
.- The item MUST be an artifact descriptor representing a manifest. Descriptors to blobs are not supported. The registry MUST return a
400
response code whensubject
is not found in the same repository, and not a manifest.
- The item MUST be an artifact descriptor representing a manifest. Descriptors to blobs are not supported. The registry MUST return a
-
annotations
string-string mapThis OPTIONAL property contains arbitrary metadata for the artifact manifest. This OPTIONAL property MUST use the annotation rules. This map MAY contain some or all of the pre-defined keys in the image-spec, and those listed below
Pre-Defined Annotation Keys:
org.opencontainers.artifact.created
date and time on which the artifact was created (string, date-time as defined by RFC 3339)
Registries and clients work with descriptors as the means to establish discovery and links. To support hashing of different types, enabling filtering, the artifactType
property is added as an OPTIONAL property to the descriptor:
{
"digest": "sha256:aaabbb",
"mediaType": "application/vnd.oci.artifact.manifest.v1+json",
"size": 312,
"artifactType": "signature/example"
}
-
artifactType
stringThis OPTIONAL property defines the type or Artifact, differentiating artifacts that use the
application/vnd.oci.artifact.manifest
. When the descriptor is used for blobs, this property MUST be empty.
The referrers
extension API is provided to discover these artifacts.
An artifact client would parse the returned artifact descriptors, determining which artifact manifest they will pull and process.
The referrers
API returns all artifacts that have a subject
of the given manifest digest.
Reference artifact requests are scoped to a repository, ensuring access rights for the repository can be used as authorization for the referenced artifacts.
The referrers
API is provided on the distribution-spec paths as described below.
The path of the referrers API provides consistent namespace/repository paths, enabling registry operators to implement consistent auth access, using existing tokens for content.
template:
GET /v2/{repository}/_oci/artifacts/referrers?digest={digest}
expanded example:
GET /v2/hello-world/_oci/artifacts/referrers?digest=sha256:abc123
- Implementations MUST implement paging.
- Implementations MUST implement sorting
- Implementations SHOULD implement
artifactType
filtering.
Some artifacts types including signatures, may return multiple signatures of the same artifactType
.
For cases where multiple artifacts are returned to the client, it may be necessary to pull each artifact's manifest in order to determine whether or not the full artifact is needed.
Maintainers of the standards utilizing references SHOULD define standard sets of annotations that will allow clients to determine whether or not each artifact needs to be downloaded in full.
While this will cause additional round trips, manifests are typically small in comparison to the full pull time for a manifest and its blobs or layers.
This paged result MUST return the following elements:
referrers
: A list of artifact descriptors that reference the given manifest. The list MUST include these references even if the given manifest does not exist in the repository. The list MUST be empty if there are no artifacts referencing the given manifest.
example result of artifacts that reference the hello-world@sha256:abc123
image:
{
"referrers": [
{
"digest": "sha256:aaabbb",
"mediaType": "application/vnd.oci.artifact.manifest.v1+json",
"artifactType": "signature/example",
"size": 312
},
...
]
}
example result for a manifest that has no artifacts referencing it:
{
"referrers": []
}
The referrers
API MUST provide for paging, returning a list of artifact descriptors.
Page size can be specified by adding a n
parameter to the request URL, indicating that the response should be limited to n
results.
- If specified, servers MAY return up to
n
items from the entire result set. - When
n
is not provided, servers MAY return a default number of items, which may be implementation specific.
A paginated flow begins as:
template:
GET /v2/{repository}/_oci/artifacts/referrers?digest={digest}&n=<integer>
expanded example:
GET /v2/{repository}/_oci/artifacts/referrers?digest=sha256:abc123&n=10
The above specifies that a referrers response should be returned limiting the number of results to n
.
The response to such a request would look as follows:
200 OK
RefType-Api-Version:reftype/1.0
Link: <url>; rel="next"
{
"referrers": [
{
"digest": "<string>",
"mediaType": "<string>",
"artifactType": "<string>",
"size": <integer>
},
...
]
}
The above includes up to n
items from the result set. If there are more items, the URL for the next collection is
encoded in a RFC5988 Link
header, as a "next" relation. Clients SHOULD treat this as an opaque value and not try to
construct it themselves.
- The presence of the
Link
header communicates to the client that the server has more items. Clients are expected to follow the link to fetch the next page of items, irrespective of the number of items received in the current response. - If the header is not present, clients can assume that all items have been received.
NOTE: In the request template above, the brackets around the url are required.
For example, if the url is:
http://example.com/v2/hello-world/_oci/artifacts/referrers?digest=sha256:abc123&n=5&nextToken=abc
The value of the header would be:
<http://example.com/v2/hello-world/_oci/artifacts/referrers?digest=sha256:abc123&n=5&nextToken=abc>; rel="next"`.
Please see RFC5988 for details.
The /referrers
API MUST allow for artifacts to be sorted by the date and time in which they were created, which SHOULD be included in the artifact manifest's list of annotations
.
The artifact's creation time MUST be the value of the org.oci.artifact.created
annotation.
The results of the /referrers
API MUST list artifacts that were created more recently first.
Artifacts that do not have the org.oci.artifact.created
annotation MUST appear after those with creation times specified in the list of results.
There is no specified ordering for artifacts that do not include the creation time in their list of annotations
.
The referrers
API MAY provide for filtering of artifactTypes
.
Artifact clients MUST account for implementations that MAY NOT support filtering.
Artifact clients MUST revert to client side filtering to determine which artifactTypes
they will process.
Request referenced artifacts by artifactType
template:
GET /v2/{repository}/_oci/artifacts/referrers?digest={digest}&n=10&artifactType={artifactType}
expanded example:
GET /v2/hello-world/_oci/artifacts/referrers?digest=sha256:abc123&n=10&artifactType=signature%2Fexample
Following the distribution-spec push API, all blobs and the subject
descriptors SHOULD exist when pushed to a distribution instance.
Registries MAY treat the lifecycle of a reference type object, such as an SBoM or signature, as being tied to its subject
. In such registries, when the subject
is deleted or marked for garbage collection, the defined artifact is subject to deletion as well, unless the artifact is tagged.