Skip to content
This repository has been archived by the owner on May 15, 2024. It is now read-only.

Latest commit

 

History

History
80 lines (55 loc) · 5.96 KB

artifact-manifest.md

File metadata and controls

80 lines (55 loc) · 5.96 KB
Raw

ORAS Artifact Manifest Spec

The ORAS 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, on-demand loading, 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.

This section defines the application/vnd.cncf.oras.artifact.manifest.v1+json media type.

ORAS Artifact Manifest Properties

The artifact.manifest provides an optional collection of blobs, an optional subject reference to the manifest of another artifact and an artifactType to differentiate types of artifacts (such as signatures, sboms and security scan results)

  • mediaType string

    This REQUIRED field contains the mediaType of this document, differentiating from image-manifest and image-index. The mediaType for this manifest type MUST be application/vnd.cncf.oras.artifact.manifest.v1+json, where the version WILL change to reflect newer versions.

  • artifactType string

    The REQUIRED artifactType is a unique value, as registered with iana.org. The artifactType values are equivalent to the values used in the manifest.config.mediaType in OCI Artifacts. Examples include sbom/example, application/vnd.cncf.notary.v2. For details on creating a unique artifactType, see OCI Artifact Authors Guidance

  • blobs array of objects

    An 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.
    • An encountered [descriptors].descriptor.mediaType that is unknown to the implementation MUST be persisted as a blob.

  • subject descriptor

    An 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 when subject is not found in the same repository, and not a manifest.

  • annotations string-string map

    This 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 listed below.

    Pre-Defined Annotation Keys: This defines a set of keys that have been pre-defined for use by authors of ORAS artifacts.

    • io.cncf.oras.artifact.created date and time on which the artifact was created (string, date-time as defined by RFC 3339)

Example ORAS Artifact Manifests

Push Validation

Following the distribution-spec push api, all blobs and the subject descriptors SHOULD exist when pushed to a distribution instance.

Lifecycle Management

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.

Further Reading