diff --git a/config.md b/config.md index 7ee028b58..48ecf5212 100644 --- a/config.md +++ b/config.md @@ -28,7 +28,8 @@ Changing it means creating a new derived image, instead of changing the existing A layer DiffID is a SHA256 digest over the layer's uncompressed tar archive and serialized in the descriptor digest format, e.g., `sha256:a9561eb1b190625c9adb5a9513e72c4dedafc1cb2d4c5236c9a6957ec7dfd5a9`. Layers must be packed and unpacked reproducibly to avoid changing the layer DiffID, for example by using tar-split to save the tar headers. -NOTE: the DiffID is different than the digest in the manifest list because the manifest digest is taken over the gzipped layer for `application/vnd.oci.image.layer.v1.tar+gzip` types. +The difference between DiffIDs and the layer digests in the [manifest's `layers`](manifest.md#image-manifest-property-descriptions) is that the layer digest is taken over the blob regardless of compression, while the DiffID is taken after removing any compression. +For an `application/vnd.oci.image.layer.tar+gzip` layer, the layer digest is taken over the `application/vnd.oci.image.layer.tar+gzip` content, while the DiffID is take over the `application/vnd.oci.image.layer.tar` content. ### Layer ChainID diff --git a/img/media-types.dot b/img/media-types.dot index aa51bc215..607465d4f 100644 --- a/img/media-types.dot +++ b/img/media-types.dot @@ -3,7 +3,7 @@ digraph G { manifestList [shape=note, label="Manifest list\n<>\napplication/vnd.oci.image.manifest.list.v1+json"] manifest [shape=note, label="Image manifest\napplication/vnd.oci.image.manifest.v1+json"] config [shape=note, label="Image JSON\napplication/vnd.oci.image.config.v1+json"] - layer [shape=note, label="Layer tar+gzip\napplication/vnd.oci.image.layer.v1.tar+gzip\napplication/vnd.oci.image.layer.nondistributable.v1.tar+gzip"] + layer [shape=note, label="Layer tar archive\napplication/vnd.oci.image.layer.v1.tar\napplication/vnd.oci.image.layer.nondistributable.v1.tar"] } manifestList -> manifest [label="1..*"] diff --git a/img/media-types.png b/img/media-types.png index aea24f7ff..a9e9606fa 100644 Binary files a/img/media-types.png and b/img/media-types.png differ diff --git a/layer.md b/layer.md index f28b03ee6..a8d9b9f4f 100644 --- a/layer.md +++ b/layer.md @@ -4,12 +4,12 @@ This document describes how to serialize a filesystem and filesystem changes lik One or more layers are applied on top of each other to create a complete filesystem. This document will use a concrete example to illustrate how to create and consume these filesystem layers. -This section defines the `application/vnd.oci.image.layer.v1.tar+gzip` and `application/vnd.oci.image.layer.nondistributable.v1.tar+gzip` [media types](media-types.md). +This section defines the `application/vnd.oci.image.layer.v1.tar` and `application/vnd.oci.image.layer.nondistributable.v1.tar` [media types](media-types.md). ## Distributable Format -Layer Changesets for the [mediatype](./media-types.md) `application/vnd.oci.image.layer.v1.tar+gzip` MUST be packaged in a [tar archive][tar-archive] compressed with [gzip][gzip]. -Layer Changesets for the [mediatype](./media-types.md) `application/vnd.oci.image.layer.v1.tar+gzip` MUST NOT include duplicate entries for file paths in the resulting [tar archive][tar-archive]. +Layer Changesets for the [media type](./media-types.md) `application/vnd.oci.image.layer.v1.tar` MUST be packaged in [tar archive][tar-archive]. +Layer Changesets for the [media type](./media-types.md) `application/vnd.oci.image.layer.v1.tar` MUST NOT include duplicate entries for file paths in the resulting [tar archive][tar-archive]. ## Change Types @@ -208,7 +208,7 @@ To signify that the resource `./etc/my-app-config` MUST be removed when the chan ## Applying Changesets -Layer Changesets of [mediatype](./media-types.md) `application/vnd.oci.image.layer.v1.tar+gzip` are _applied_, rather than simply extracted as tar archives. +Layer Changesets of [media type](./media-types.md) `application/vnd.oci.image.layer.v1.tar` are _applied_, rather than simply extracted as tar archives. Applying a layer changeset requires special consideration for the [whiteout](#whiteouts) files. @@ -311,11 +311,10 @@ Any given image is likely to be composed of several of these Image Filesystem Ch Certain layers, due to legal requirements, may not be regularly distributable. Typically, such layers are downloaded directly from a distributor but are never uploaded. -Layers that have these restrictions SHOULD be tagged with an alternative mediatype of `application/vnd.oci.image.layer.nondistributable.v1.tar+gzip`. +Layers that have these restrictions SHOULD be tagged with an alternative media type of `application/vnd.oci.image.layer.nondistributable.v1.tar`. [Descriptors](descriptor.md) referencing these layers MAY include `urls` for downloading these layers. It is implementation-defined whether or not implementations upload layers tagged with this media type. [libarchive-tar]: https://github.com/libarchive/libarchive/wiki/ManPageTar5#POSIX_ustar_Archives [gnu-tar-standard]: http://www.gnu.org/software/tar/manual/html_node/Standard.html [tar-archive]: https://en.wikipedia.org/wiki/Tar_(computing) -[gzip]: http://www.zlib.org/rfc-gzip.html diff --git a/manifest.md b/manifest.md index 900162b08..830195993 100644 --- a/manifest.md +++ b/manifest.md @@ -54,11 +54,13 @@ Unlike the [Manifest List](manifest-list.md), which contains information about a This [descriptor property](descriptor.md#properties) has additional restrictions for `layers[]`. Implementations MUST support at least the following media types: - - [`application/vnd.oci.image.layer.v1.tar+gzip`](layer.md) - - [`application/vnd.oci.image.layer.nondistributable.v1.tar+gzip`](layer.md#non-distributable-layers) + - [`application/vnd.oci.image.layer.v1.tar`](layer.md) + - [`application/vnd.oci.image.layer.nondistributable.v1.tar`](layer.md#non-distributable-layers) Manifests concerned with portability SHOULD use one of the above media types. + Entries in this field will frequently use the [`+gzip` structured syntax suffix](media-types.md#the-gzip-structured-syntax-suffix). + - **`annotations`** *string-string map* This OPTIONAL property contains arbitrary metadata for the image manifest. diff --git a/media-types.md b/media-types.md index 6aa42bfd7..578d23a81 100644 --- a/media-types.md +++ b/media-types.md @@ -6,8 +6,48 @@ The following media types identify the formats described here and their referenc - `application/vnd.oci.image.manifest.list.v1+json`: [Manifest list](manifest-list.md#manifest-list) - `application/vnd.oci.image.manifest.v1+json`: [Image manifest](manifest.md#image-manifest) - `application/vnd.oci.image.config.v1+json`: [Image config](config.md) -- `application/vnd.oci.image.layer.v1.tar+gzip`: ["Layer", as a gzipped tar archive](layer.md) -- `application/vnd.oci.image.layer.nondistributable.v1.tar+gzip`: ["Layer", as a gzipped tar archive with distribution restrictions](layer.md#non-distributable-layers) +- `application/vnd.oci.image.layer.v1.tar`: ["Layer", as a tar archive](layer.md) +- `application/vnd.oci.image.layer.nondistributable.v1.tar`: ["Layer", as a tar archive with distribution restrictions](layer.md#non-distributable-layers) + +## Suffixes + +[RFC 6839][rfc6839] defines several structured syntax suffixes for use with media types. +This section adds additional structured syntax suffixes for use with media types in OCI Image contexts. + +### The +gzip Structured Syntax Suffix + +[GZIP][rfc1952] is a widely used compression format. +The media type [`application/gzip`][rfc6713] has been registered for such files. +The suffix `+gzip` MAY be used with any media type whose representation follows that established for `application/gzip`. +The media type structured syntax suffix registration form follows: + +Name: GZIP file format + +`+suffix`: `+gzip` + +References: [[GZIP][rfc1952]] + +Encoding considerations: GZIP is a binary encoding. + +Fragment identifier considerations: + +The syntax and semantics of fragment identifiers specified for `+gzip` SHOULD be as specified for `application/gzip`. +(At publication of this document, there is no fragment identification syntax defined for `application/gzip`.) +The syntax and semantics for fragment identifiers for a specific `xxx/yyy+gzip` SHOULD be processed as follows: + +* For cases defined in `+gzip`, where the fragment identifier resolves per the `+gzip` rules, then process as specified in `+gzip`. +* For cases defined in `+gzip`, where the fragment identifier does not resolve per the `+gzip` rules, then process as specified in `xxx/yyy+gzip`. +* For cases not defined in `+gzip`, then process as specified in `xxx/yyy+gzip`. + +Interoperability considerations: n/a + +Security considerations: + +See the "Security Considerations" sections of [RFC 1952][rfc1952] and [RFC 6713][rfc6713]. +Each individual media type registered with a `+gzip` suffix can have additional security considerations. + +Implementations MUST support the `+gzip` suffix for all [OCI Image Media Types](#oci-image-media-types). +For example, they MUST support `application/vnd.oci.image.layer.v1.tar+gzip` and `application/vnd.oci.image.layer.nondistributable.v1.tar+gzip` for [manifest `layers`](manifest.md#image-manifest-property-descriptions) and `application/vnd.oci.image.manifest.v1+json+gzip` for [manifest list `manifests`](manifest-list.md#manifest-list-property-descriptions). ## Media Type Conflicts @@ -41,11 +81,13 @@ This section shows where the OCI Image Specification is compatible with formats - [application/vnd.docker.distribution.manifest.v2+json](https://github.com/docker/distribution/blob/master/docs/spec/manifest-v2-2.md#image-manifest-field-descriptions) -### application/vnd.oci.image.rootfs.tar.gzip +### application/vnd.oci.image.layer.v1.tar **Interchangeable and fully compatible mime-types** -- [application/vnd.docker.image.rootfs.diff.tar.gzip](https://github.com/docker/docker/blob/master/image/spec/v1.md#creating-an-image-filesystem-changeset) +- With `+gzip` + + - [application/vnd.docker.image.rootfs.diff.tar.gzip](https://github.com/docker/docker/blob/master/image/spec/v1.md#creating-an-image-filesystem-changeset) ### application/vnd.oci.image.config.v1+json @@ -61,3 +103,7 @@ The following figure shows how the above media types reference each other: [Descriptors](descriptor.md) are used for all references. The manifest list being a "fat manifest" references one or more image manifests per target platform. An image manifest references exactly one target configuration and possibly many layers. + +[rfc1952]: https://tools.ietf.org/html/rfc1952 +[rfc6713]: https://tools.ietf.org/html/rfc6713 +[rfc6839]: https://tools.ietf.org/html/rfc6839 diff --git a/specs-go/v1/mediatype.go b/specs-go/v1/mediatype.go index d6592f549..75713ee0b 100644 --- a/specs-go/v1/mediatype.go +++ b/specs-go/v1/mediatype.go @@ -25,11 +25,11 @@ const ( MediaTypeImageManifestList = "application/vnd.oci.image.manifest.list.v1+json" // MediaTypeImageLayer is the media type used for layers referenced by the manifest. - MediaTypeImageLayer = "application/vnd.oci.image.layer.v1.tar+gzip" + MediaTypeImageLayer = "application/vnd.oci.image.layer.v1.tar" // MediaTypeImageLayerNonDistributable is the media type for layers referenced by // the manifest but with distribution restrictions. - MediaTypeImageLayerNonDistributable = "application/vnd.oci.image.layer.nondistributable.v1.tar+gzip" + MediaTypeImageLayerNonDistributable = "application/vnd.oci.image.layer.nondistributable.v1.tar" // MediaTypeImageConfig specifies the media type for the image configuration. MediaTypeImageConfig = "application/vnd.oci.image.config.v1+json"