|
| 1 | +# OCI Artifact Manifest Spec (Phase-1 Reference Types) |
| 2 | +The OCI artifact manifest generalizes the use cases of [OCI image manifest][oci-image-manifest-spec] by removing constraints defined on the image-manifest such as a required `config` object and required & ordinal `layers`. It then adds a `subjectManifest` property supporting reference types. 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` or `image.index`. 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 doesn't yet implement the new capabilities. |
| 3 | + |
| 4 | +To enable a fall 2021 focus on supply chain security, **Phase 1** will narrowly focus on Reference Type support, giving time for further generalization with less time constraints. |
| 5 | + |
| 6 | +For usage and scenarios, see [artifact-manifest.md](./artifact-manifest.md) |
| 7 | + |
| 8 | +## Example OCI Artifact Manifests |
| 9 | + |
| 10 | +The following are Phase 1 examples: |
| 11 | + |
| 12 | +- [`net-monitor:v1` oci container image](./artifact-manifest/net-monitor-oci-image.json) |
| 13 | +- [`net-monitor:v1` notary v2 signature](./artifact-manifest/net-monitor-image-signature.json) |
| 14 | +- [`net-monitor:v1` sample sbom](./artifact-manifest/net-monitor-image-sbom.json) |
| 15 | +- [`net-monitor:v1` nydus image with on-demand loading](./artifact-manifest/net-monitor-image-nydus-ondemand-loading.json) |
| 16 | + |
| 17 | +## OCI Artifact Manifest Properties |
| 18 | + |
| 19 | +For **Phase 1**, an artifact manifest provides an optional collection of blobs and a reference to the manifest of another artifact. |
| 20 | + |
| 21 | +- **`schemaVersion`** *int* |
| 22 | + |
| 23 | + This REQUIRED property specifies the artifact manifest schema version. |
| 24 | + For this version of the specification, this MUST be `3`. The value of this field WILL change as the manifest schema evolves. Minor version changes to the `oci.artifact.manifest` spec MUST be additive, while major version changes MAY be breaking. Artifact clients MUST implement version checking to allow for future, yet unknown changes. Artifact clients MUST ignore additive properties to minor versions. Artifact clients MAY support major changes, with no guarantee major changes MAY impose breaking changing behaviors. Artifact authors MAY support new and older schemaVersions to provide the best user experience. |
| 25 | + |
| 26 | +- **`mediaType`** *string* |
| 27 | + |
| 28 | + This field contains the `mediaType` of this document, differentiating from [image-manifest][oci-image-manifest-spec] and [oci-image-index]. The mediaType for this manifest type MUST be `application/vnd.oci.artifact.manifest.v1+json`, where the version WILL change to reflect newer versions. Artifact authors SHOULD support multiple `mediaType` versions to provide the best user experience for their artifact type. |
| 29 | + |
| 30 | +- **`artifactType`** *string* |
| 31 | + |
| 32 | + Phase 1 of the OCI Artifact spec will support reference types to existing [OCI Artifacts][oci-artifacts]. The REQUIRED `artifactType` is unique value, as registered with iana.org. See [registering unique types.][registering-iana]. The `artifactType` is equivalent to OCI Artifacts that used the `manifest.config.mediaType` to differentiate the type of artifact. Artifact authors that implement `oci.artifact.manifest` use `artifactType` to differentiate the type of artifact. example:(`example.sbom` from `cncf.notary`). |
| 33 | + |
| 34 | +- **`blobs`** *array of objects* |
| 35 | + |
| 36 | + An OPTIONAL collection of 0 or more blobs. The blobs array is analogous to [oci.image.manifest layers][oci-image-manifest-spec-layers], however unlike [image-manifest][oci-image-manifest-spec], the ordering of blobs is specific to the artifact type. Some artifacts may choose an overlay of files, while other artifact types may store indepdent collections of files. |
| 37 | + |
| 38 | + - Each item in the array MUST be a [descriptor][descriptor], and MUST NOT refer to another `manifest` providing dependency closure. |
| 39 | + - The max number of blobs is not defined, but MAY be limited by [distribution-spec][oci-distribution-spec] implementations. |
| 40 | + - An encountered `descriptor.mediaType` that is unknown to the implementation MUST be ignored. |
| 41 | + |
| 42 | +- **`subjectManifest`** *descriptor* |
| 43 | + |
| 44 | + An OPTIONAL reference to any existing manifest within the repository. When specified, the artifact is said to be dependent upon the referenced `subjectManifest`. |
| 45 | + - The item MUST be a [descriptor][descriptor] representing a manifest. Descriptors to blobs are not supported. The registry MUST return a `400` response code when `subjectManifest` is not found in the same repository, and not a manifest. |
| 46 | + |
| 47 | +- **`annotations`** *string-string map* |
| 48 | + |
| 49 | + This OPTIONAL property contains arbitrary metadata for the image manifest. |
| 50 | + This OPTIONAL property MUST use the [annotation rules](annotations.md#rules). |
| 51 | + |
| 52 | + See [Pre-Defined Annotation Keys][annotations] |
| 53 | + |
| 54 | +## Push Validation |
| 55 | + |
| 56 | +Following the [distribution-spec push api](https://github.com/opencontainers/distribution-spec/blob/main/spec.md#push), all `blobs` *and* the `subjectManifest` descriptors SHOULD exist when pushed to a distribution instance. |
| 57 | + |
| 58 | +## Lifecycle Management |
| 59 | + |
| 60 | +For Phase 1, artifact types will be limited to reference types. A reference type is an artifact that doesn't have a lifecycle unto itself. A container image is said to have an independent lifecycle. A reference type, such as an SBoM or signature have a lifecycle tied to the `subjectManifest`. When the `subjectManifest` is deleted or marked for garbage collection, the defined artifact is subject to deletion as well. A distribution instance SHOULD delete, (refCount -1) the artifact when the `subjectManifest` is deleted. |
| 61 | + |
| 62 | +### Tagged `referenceTypes` |
| 63 | + |
| 64 | +As signatures and SBoMs are not considered independent artifact types, they SHOULD NOT have a tag, simplifying the lifecycle management. As the `subjectManifest` is marked for deletion (refCount=0), the `referenctType` is also marked for deletion (refCount -1). However, these artifacts MAY have tags as future versions of the artifact manifest MAY support independent types. |
| 65 | + |
| 66 | +[oci-artifacts]: https://github.com/opencontainers/artifacts |
| 67 | +[oci-config]: https://github.com/opencontainers/image-spec/blob/master/config.md |
| 68 | +[oci-image-manifest-spec]: https://github.com/opencontainers/image-spec/blob/master/manifest.md |
| 69 | +[oci-image-manifest-spec-layers]: https://github.com/opencontainers/image-spec/blob/master/manifest.md#image-manifest-property-descriptions |
| 70 | +[oci-image-index]: https://github.com/opencontainers/image-spec/blob/master/image-index.md |
| 71 | +[oci-distribution-spec]: https://github.com/opencontainers/distribution-spec |
| 72 | +[media-type]: https://github.com/opencontainers/image-spec/blob/master/media-types.md |
| 73 | +[artifact-type]: https://github.com/opencontainers/artifacts/blob/master/artifact-authors.md#defining-a-unique-artifact-type |
| 74 | +[registering-iana]: ./artifact-authors.md#registering-unique-types-with-iana |
| 75 | +[descriptor]: https://github.com/opencontainers/image-spec/blob/master/descriptor.md |
| 76 | +[annotations]: https://github.com/opencontainers/image-spec/blob/master/annotations.md |
0 commit comments