diff --git a/.github/PULL_REQUEST_TEMPLATE/maintainer_nomination.md b/.github/PULL_REQUEST_TEMPLATE/maintainer_nomination.md new file mode 100644 index 000000000..6523d7a82 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE/maintainer_nomination.md @@ -0,0 +1,21 @@ +# Nomination for a New Maintainer + +## Nominating Maintainer + +Name of the existing OCI maintainer with GitHub username + +## New Maintainer + +Name of the new maintainer with GitHub username + +## Justification + +Highlight any work contributed by the new maintainer. Examples of contributions may be: +- Community involvement in mailing lists and meetings +- Involvement in any OCI working groups +- Contributions to any of the OCI git repositories + +Other considerations may be: +- Diversity of organizations +- Time involved in the community +- Personal experience working with the new maintainer diff --git a/artifact.md b/artifact.md index 30d1985c1..15fadc97a 100644 --- a/artifact.md +++ b/artifact.md @@ -1,6 +1,6 @@ # OCI Artifact Manifest Specification -The goal of the Artifact Manifest Specification is to define content addressable artifacts in order to store them along side container images in a registry. Like [OCI Images](manifest.md), OCI Artifacts may be referenced by hash of their manifests. Unlike OCI Images, OCI Artifacts are not meant to be used by any container runtime. +The goal of the Artifact Manifest Specification is to define content addressable artifacts in order to store them along side container images in a registry. Like [OCI Images](manifest.md), OCI Artifacts may be referenced by the hash of their manifest. Unlike OCI Images, OCI Artifacts are not meant to be used by any container runtime. Examples of artifacts that may be stored along with container images are Software Bill of Materials (SBOM), Digital Signatures, Provenance data, Supply Chain Attestations, scan results, and Helm charts. @@ -17,11 +17,15 @@ For the media type(s) that this is compatible with see the [matrix](media-types. - **`blobs`** *string* - This OPTIONAL property contains a list of [descriptors](descriptor.md). Each descriptor represents an artifact of any IANA mediaType. The list MAY be ordered for certain artifact types like scan results. + This OPTIONAL property contains a list of [descriptors](descriptor.md). + Each descriptor represents an artifact of any IANA mediaType. + The list MAY be ordered for certain artifact types like scan results. - **`refers`** *string* - This OPTIONAL property specifies a [descriptor](descriptor.md) of a container image or another artifact. The purpose of this property is to provide a reference to the container image or artifact this artifact is related to. The "Referrers" API in the distribution specification looks for this property to list all artifacts that refer to a given artifact or container image. + This OPTIONAL property specifies a [descriptor](descriptor.md) of a container image or another artifact. + The purpose of this property is to provide a reference to the container image or artifact this artifact is related to. + The "Referrers" API in the distribution specification looks for this property to list all artifacts that refer to a given artifact or container image. - **`annotations`** *string-string map* @@ -46,7 +50,7 @@ For the media type(s) that this is compatible with see the [matrix](media-types. ## Examples -*Example showing an artifact manifest for an image signature:* +*Example showing an artifact manifest for an ice cream flavor referencing an ice cream:* ```jsonc,title=Manifest&mediatype=application/vnd.oci.artifact.manifest.v1%2Bjson { @@ -54,18 +58,18 @@ For the media type(s) that this is compatible with see the [matrix](media-types. "mediaType": "application/vnd.oci.artifact.manifest.v1+json", "blobs": [ { - "mediaType": "application/vnd.dev.cosign.simplesigning.v1+json", - "size": 210, - "digest": "sha256:1119abab63e605dcc281019bad0424744178b6f61ba57378701fe7391994c999" + "mediaType": "application/vnd.icecream.flavor", + "size": 123, + "digest": "sha256:87923725d74f4bfb94c9e86d64170f7521aad8221a5de834851470ca142da630" } ], "refers": { - "mediaType": "application/vnd.oci.image.manifest.v1+json", - "size": 7682, - "digest": "sha256:5b0bcabd1ed22e9fb1310cf6c2dec7cdef19f0ad69efa1f392e94a4333501270" + "mediaType": "application/vnd.icecream", + "size": 1234, + "digest": "sha256:cc06a2839488b8bd2a2b99dcdc03d5cfd818eed72ad08ef3cc197aac64c0d0a0" }, "annotations": [ - "org.opencontainers.artifact.description": "cosign signature for image:tag", + "org.opencontainers.artifact.description": "vanilla surprise", "org.opencontainers.artifact.created": "2022-04-05T14:30Z" ] } diff --git a/descriptor.md b/descriptor.md index e8ca10326..e571a0bfb 100644 --- a/descriptor.md +++ b/descriptor.md @@ -1,11 +1,12 @@ # OCI Content Descriptors -* An OCI image consists of several different components, arranged in a [Merkle Directed Acyclic Graph (DAG)](https://en.wikipedia.org/wiki/Merkle_tree). -* References between components in the graph are expressed through _Content Descriptors_. -* A Content Descriptor (or simply _Descriptor_) describes the disposition of the targeted content. -* A Content Descriptor includes the type of the content, a content identifier (_digest_), and the byte-size of the raw content. -* Descriptors SHOULD be embedded in other formats to securely reference external content. -* Other formats SHOULD use descriptors to securely reference external content. +- An OCI image consists of several different components, arranged in a [Merkle Directed Acyclic Graph (DAG)](https://en.wikipedia.org/wiki/Merkle_tree). +- References between components in the graph are expressed through _Content Descriptors_. +- A Content Descriptor (or simply _Descriptor_) describes the disposition of the targeted content. +- A Content Descriptor includes the type of the content, a content identifier (_digest_), and the byte-size of the raw content. + Optionally, it includes the type of artifact it is describing. +- Descriptors SHOULD be embedded in other formats to securely reference external content. +- Other formats SHOULD use descriptors to securely reference external content. This section defines the `application/vnd.oci.descriptor.v1+json` [media type](media-types.md). @@ -22,6 +23,10 @@ The following fields contain the primary properties that constitute a Descriptor The OCI image specification defines [several of its own MIME types](media-types.md) for resources defined in the specification. +- **`artifactType`** *string* + This OPTIONAL property contains the artifact type of the referenced content. + The value of this property MUST be the [IANA media type](https://www.iana.org/assignments/media-types/media-types.xhtml) of the artifact. + - **`digest`** *string* This REQUIRED property is the _digest_ of the targeted content, conforming to the requirements outlined in [Digests](#digests). @@ -68,7 +73,7 @@ The _algorithm_ specifies the cryptographic hash function and encoding used for A digest string MUST match the following [grammar](considerations.md#ebnf): -``` +```text digest ::= algorithm ":" encoded algorithm ::= algorithm-component (algorithm-separator algorithm-component)* algorithm-component ::= [a-z0-9]+ @@ -104,12 +109,14 @@ Implementations MAY employ [canonicalization](considerations.md#canonicalization ### Digest calculations A _digest_ is calculated by the following pseudo-code, where `H` is the selected hash algorithm, identified by string ``: -``` + +```text let ID(C) = Descriptor.digest let C = let D = ':' + Encode(H(C)) let verified = ID(C) == D ``` + Above, we define the content identifier as `ID(C)`, extracted from the `Descriptor.digest` field. Content `C` is a string of bytes. Function `H` returns the hash of `C` in bytes and is passed to function `Encode` and prefixed with the algorithm to obtain the digest. @@ -190,6 +197,17 @@ In the following example, the descriptor indicates that the referenced manifest } ``` +In the following example, the descriptor indicates the type of artifact it is referencing: + +```json,title=Content%20Descriptor&mediatype=application/vnd.oci.descriptor.v1%2Bjson +{ + "mediaType": "application/vnd.icecream.flavor", + "size": 123, + "digest": "sha256:87923725d74f4bfb94c9e86d64170f7521aad8221a5de834851470ca142da630", + "artifactType": "icecream_flavor" +} +``` + [rfc3986]: https://tools.ietf.org/html/rfc3986 [rfc4634-s4.1]: https://tools.ietf.org/html/rfc4634#section-4.1 [rfc4634-s4.2]: https://tools.ietf.org/html/rfc4634#section-4.2 diff --git a/manifest.md b/manifest.md index 40a3f8996..7094782ae 100644 --- a/manifest.md +++ b/manifest.md @@ -65,7 +65,7 @@ Unlike the [image index](image-index.md), which contains information about a set Entries in this field will frequently use the `+gzip` types. -- **`refers`** *string* +- **`refers`** *[descriptor](descriptor.md)* This OPTIONAL property specifies a [descriptor](descriptor.md) of another image or [artifact](artifact.md). Clients may use this property to take advantage of the [`referrers` API](https://github.com/oci-playground/distribution-spec/blob/pr/spec.md#endpoints), to encode a reference to a related image or artifact. @@ -106,7 +106,7 @@ Unlike the [image index](image-index.md), which contains information about a set "digest": "sha256:ec4b8955958665577945c89419d1af06b5f7636b4ac3da7f12184802ad867736" } ], - "refers': { + "refers": { "mediaType": "application/vnd.oci.image.manifest.v1+json", "size": 7682, "digest": "sha256:5b0bcabd1ed22e9fb1310cf6c2dec7cdef19f0ad69efa1f392e94a4333501270" diff --git a/specs-go/v1/artifact.go b/specs-go/v1/artifact.go new file mode 100644 index 000000000..2a18ce106 --- /dev/null +++ b/specs-go/v1/artifact.go @@ -0,0 +1,34 @@ +// Copyright 2022 The Linux Foundation +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +package v1 + +// Artifact describes an artifact manifest. +// This structure provides `application/vnd.oci.artifact.manifest.v1+json` mediatype when marshalled to JSON. +type Artifact struct { + // MediaType is the media type of the object this schema refers to. + MediaType string `json:"mediaType"` + + // ArtifactType is the IANA media type of the artifact this schema refers to. + ArtifactType string `json:"artifactType"` + + // Blobs is a collection of blobs referenced by this manifest. + Blobs []Descriptor `json:"blobs,omitempty"` + + // Refers is an optional link to any existing manifest within the repository. + Refers *Descriptor `json:"refers,omitempty"` + + // Annotations contains arbitrary metadata for the artifact manifest. + Annotations map[string]string `json:"annotations,omitempty"` +} diff --git a/specs-go/v1/descriptor.go b/specs-go/v1/descriptor.go index 94f19be62..03a3665b3 100644 --- a/specs-go/v1/descriptor.go +++ b/specs-go/v1/descriptor.go @@ -1,4 +1,4 @@ -// Copyright 2016 The Linux Foundation +// Copyright 2016-2022 The Linux Foundation // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. @@ -29,6 +29,9 @@ type Descriptor struct { // Size specifies the size in bytes of the blob. Size int64 `json:"size"` + // ArtifactType is the type of artifact this schema refers to. + ArtifactType string `json:"artifactType,omitempty"` + // URLs specifies a list of URLs from which this object MAY be downloaded URLs []string `json:"urls,omitempty"` diff --git a/specs-go/v1/manifest.go b/specs-go/v1/manifest.go index 8212d520c..7f2df9863 100644 --- a/specs-go/v1/manifest.go +++ b/specs-go/v1/manifest.go @@ -1,4 +1,4 @@ -// Copyright 2016 The Linux Foundation +// Copyright 2016-2022 The Linux Foundation // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. @@ -30,6 +30,9 @@ type Manifest struct { // Layers is an indexed list of layers referenced by the manifest. Layers []Descriptor `json:"layers"` + // Refers is an optional link to any existing manifest within the repository. + Refers *Descriptor `json:"refers,omitempty"` + // Annotations contains arbitrary metadata for the image manifest. Annotations map[string]string `json:"annotations,omitempty"` } diff --git a/specs-go/v1/mediatype.go b/specs-go/v1/mediatype.go index 4f35ac134..935b481e3 100644 --- a/specs-go/v1/mediatype.go +++ b/specs-go/v1/mediatype.go @@ -54,4 +54,7 @@ const ( // MediaTypeImageConfig specifies the media type for the image configuration. MediaTypeImageConfig = "application/vnd.oci.image.config.v1+json" + + // MediaTypeArtifactManifest specifies the media type for a content descriptor. + MediaTypeArtifactManifest = "application/vnd.oci.artifact.manifest.v1+json" )