Skip to content

Commit 155b8ac

Browse files
vbattsvbatts
committed
*: update for oc/image-spec
WIP
1 parent c1ff36f commit 155b8ac

File tree

2 files changed

+69
-103
lines changed

2 files changed

+69
-103
lines changed

‎manifest.md‎

Lines changed: 68 additions & 93 deletions
Original file line numberDiff line numberDiff line change
@@ -4,124 +4,100 @@ draft = true
44
+++
55
<![end-metadata]-->
66

7-
# Image Manifest Version 2, Schema 2
8-
9-
This document outlines the format of of the V2 image manifest, schema version 2.
10-
The original (and provisional) image manifest for V2 (schema 1), was introduced
11-
in the Docker daemon in the [v1.3.0
12-
release](https://github.com/docker/docker/commit/9f482a66ab37ec396ac61ed0c00d59122ac07453)
13-
and is specified in the [schema 1 manifest definition](./manifest-v2-1.md)
7+
# Image Manifest
148

15-
This second schema version has two primary goals. The first is to allow
16-
multi-architecture images, through a "fat manifest" which references image
17-
manifests for platform-specific versions of an image. The second is to
18-
move the Docker engine towards content-addressable images, by supporting
19-
an image model where the image's configuration can be hashed to generate
20-
an ID for the image.
9+
The first goal is content-addressable images, by supporting an image model where the image's configuration can be hashed to generate an ID for the image and its components.
10+
The second goal is to allow multi-architecture images, through a "fat manifest" which references image manifests for platform-specific versions of an image.
11+
The third goal is to be translatable to the [OpenContainers/runtime-spec](https://github.com/opencontainers/runtime-spec)
2112

2213
# Media Types
2314

24-
The following media types are used by the manifest formats described here, and
25-
the resources they reference:
15+
The following media types are used by the manifest formats described here, and the resources they reference:
2616

27-
- `application/vnd.docker.distribution.manifest.v1+json`: schema1 (existing manifest format)
28-
- `application/vnd.docker.distribution.manifest.v2+json`: New image manifest format (schemaVersion = 2)
29-
- `application/vnd.docker.distribution.manifest.list.v2+json`: Manifest list, aka "fat manifest"
30-
- `application/vnd.docker.image.rootfs.diff.tar.gzip`: "Layer", as a gzipped tar
31-
- `application/vnd.docker.container.image.v1+json`: Container config JSON
17+
- `application/vnd.oci.image.manifest.v1+json`: Image manifest format
18+
- `application/vnd.oci.image.manifest.list.v1+json`: Manifest list, aka "fat manifest"
19+
- `application/vnd.oci.image.serialization.v1+json`: Container config JSON
20+
- `application/vnd.oci.image.rootfs.tar.gzip`: "Layer", as a gzipped tar
3221

3322
## Manifest List
3423

35-
The manifest list is the "fat manifest" which points to specific image manifests
36-
for one or more platforms. Its use is optional, and relatively few images will
37-
use one of these manifests. A client will distinguish a manifest list from an
38-
image manifest based on the Content-Type returned in the HTTP response.
24+
The manifest list is the "fat manifest" which points to specific image manifests for one or more platforms.
25+
Its use is optional, and relatively few images will use one of these manifests.
26+
A client will distinguish a manifest list from an image manifest based on the Content-Type returned in the HTTP response.
3927

4028
## *Manifest List* Field Descriptions
4129

4230
- **`schemaVersion`** *int*
43-
44-
This field specifies the image manifest schema version as an integer. This
45-
schema uses the version `2`.
31+
32+
This field specifies the image manifest schema version as an integer.
33+
This schema uses the version `0`.
4634

4735
- **`mediaType`** *string*
4836

49-
The MIME type of the manifest list. This should be set to
50-
`application/vnd.docker.distribution.manifest.list.v2+json`.
37+
This REQUIRED property contains the MIME type of the referenced object.
38+
This should be set to `application/vnd.oci.image.manifest.list.v1+json`.
5139

5240
- **`manifests`** *array*
5341

54-
The manifests field contains a list of manifests for specific platforms.
42+
This REQUIRED property contains a list of manifests for specific platforms.
43+
While the property MUST be present, the size of the array MAY be zero.
5544

56-
Fields of a object in the manifests list are:
57-
58-
- **`mediaType`** *string*
59-
60-
The MIME type of the referenced object. This will generally be
61-
`application/vnd.docker.image.manifest.v2+json`, but it could also
62-
be `application/vnd.docker.image.manifest.v1+json` if the manifest
63-
list references a legacy schema-1 manifest.
64-
65-
- **`size`** *int*
66-
67-
The size in bytes of the object. This field exists so that a client
68-
will have an expected size for the content before validating. If the
69-
length of the retrieved content does not match the specified length,
70-
the content should not be trusted.
71-
72-
- **`digest`** *string*
45+
Fields of each object in the manifests list are:
7346

74-
The digest of the content, as defined by the
75-
[Registry V2 HTTP API Specificiation](https://docs.docker.com/registry/spec/api/#digest-parameter).
47+
- **`mediaType`** *string*
48+
49+
The MIME type of the referenced object.
50+
This will generally be `application/vnd.oci.image.manifest.v1+json`.
7651

77-
- **`platform`** *object*
52+
- **`size`** *int*
7853

79-
The platform object describes the platform which the image in the
80-
manifest runs on. A full list of valid operating system and architecture
81-
values are listed in the [Go language documentation for `$GOOS` and
82-
`$GOARCH`](https://golang.org/doc/install/source#environment)
54+
The size in bytes of the object.
55+
This field exists so that a client will have an expected size for the content before validating.
56+
If the length of the retrieved content does not match the specified length, the content should not be trusted.
8357

84-
- **`architecture`** *string*
58+
- **`digest`** *string*
8559

86-
The architecture field specifies the CPU architecture, for example
87-
`amd64` or `ppc64le`.
60+
The digest of the content, as defined by the [Registry V2 HTTP API Specificiation](https://docs.docker.com/registry/spec/api/#digest-parameter).
8861

89-
- **`os`** *string*
62+
- **`platform`** *object*
9063

91-
The os field specifies the operating system, for example
92-
`linux` or `windows`.
64+
This REQUIRED property describes the platform which the image in the manifest runs on.
65+
A full list of valid operating system and architecture values are listed in the [Go language documentation for `$GOOS` and `$GOARCH`](https://golang.org/doc/install/source#environment)
9366

94-
- **`os.version`** *string*
67+
- **`architecture`** *string*
9568

96-
The optional os.version field specifies the operating system version,
97-
for example `10.0.10586`.
69+
This REQUIRED property specified the CPU architecture, for example `amd64` or `ppc64le`.
9870

99-
- **`os.features`** *array*
71+
- **`os`** *string*
10072

101-
The optional os.features field specifies an array of strings,
102-
each listing a required OS feature (for example on Windows
103-
`win32k`).
73+
This REQUIRED property specifies the operating system, for example `linux` or `windows`.
10474

105-
- **`variant`** *string*
75+
- **`os.version`** *string*
10676

107-
The optional variant field specifies a variant of the CPU, for
108-
example `armv6l` to specify a particular CPU variant of the ARM CPU.
77+
This optional property specifies the operating system version, for example `10.0.10586`.
10978

110-
- **`features`** *array*
79+
- **`os.features`** *array*
11180

112-
The optional features field specifies an array of strings, each
113-
listing a required CPU feature (for example `sse4` or `aes`).
81+
This OPTIONAL property specifies an array of strings, each specifying a mandatory OS feature (for example on Windows `win32k`).
82+
83+
- **`variant`** *string*
84+
85+
This OPTIONAL property specifies the variant of the CPU, for example `armv6l` to specify a particular CPU variant of the ARM CPU.
86+
87+
- **`features`** *array*
88+
89+
This OPTIONAL property specifies an array of strings, each specifying a mandatory CPU feature (for example `sse4` or `aes`).
11490

11591
## Example Manifest List
11692

11793
*Example showing a simple manifest list pointing to image manifests for two platforms:*
11894
```json
11995
{
120-
"schemaVersion": 2,
121-
"mediaType": "application/vnd.docker.distribution.manifest.list.v2+json",
96+
"schemaVersion": 0,
97+
"mediaType": "application/vnd.oci.image.manifest.list.v1+json",
12298
"manifests": [
12399
{
124-
"mediaType": "application/vnd.docker.image.manifest.v2+json",
100+
"mediaType": "application/vnd.oci.image.manifest.v1+json",
125101
"size": 7143,
126102
"digest": "sha256:e692418e4cbaf90ca69d05a66403747baa33ee08806650b51fab815ad7fc331f",
127103
"platform": {
@@ -130,7 +106,7 @@ image manifest based on the Content-Type returned in the HTTP response.
130106
}
131107
},
132108
{
133-
"mediaType": "application/vnd.docker.image.manifest.v2+json",
109+
"mediaType": "application/vnd.oci.image.manifest.v1+json",
134110
"size": 7682,
135111
"digest": "sha256:5b0bcabd1ed22e9fb1310cf6c2dec7cdef19f0ad69efa1f392e94a4333501270",
136112
"platform": {
@@ -147,20 +123,19 @@ image manifest based on the Content-Type returned in the HTTP response.
147123

148124
# Image Manifest
149125

150-
The image manifest provides a configuration and a set of layers for a container
151-
image. It's the direct replacement for the schema-1 manifest.
126+
The image manifest provides a configuration and a set of layers for a container image.
152127

153128
## *Image Manifest* Field Descriptions
154129

155130
- **`schemaVersion`** *int*
156-
157-
This field specifies the image manifest schema version as an integer. This
158-
schema uses version `2`.
131+
132+
This field specifies the image manifest schema version as an integer.
133+
This schema uses version `0`.
159134

160135
- **`mediaType`** *string*
161136

162137
The MIME type of the manifest. This should be set to
163-
`application/vnd.docker.distribution.manifest.v2+json`.
138+
`application/vnd.oci.image.manifest.v1+json`.
164139

165140
- **`config`** *object*
166141

@@ -175,7 +150,7 @@ image. It's the direct replacement for the schema-1 manifest.
175150
- **`mediaType`** *string*
176151

177152
The MIME type of the referenced object. This should generally be
178-
`application/vnd.docker.container.image.v1+json`.
153+
`application/vnd.oci.image.serialization.v1+json`.
179154

180155
- **`size`** *int*
181156

@@ -198,7 +173,7 @@ image. It's the direct replacement for the schema-1 manifest.
198173
- **`mediaType`** *string*
199174

200175
The MIME type of the referenced object. This should
201-
generally be `application/vnd.docker.image.rootfs.diff.tar.gzip`.
176+
generally be `application/vnd.oci.image.rootfs.tar.gzip`.
202177

203178
- **`size`** *int*
204179

@@ -217,26 +192,26 @@ image. It's the direct replacement for the schema-1 manifest.
217192
*Example showing an image manifest:*
218193
```json
219194
{
220-
"schemaVersion": 2,
221-
"mediaType": "application/vnd.docker.distribution.manifest.v2+json",
195+
"schemaVersion": 0,
196+
"mediaType": "application/vnd.oci.image.manifest.v1+json",
222197
"config": {
223-
"mediaType": "application/vnd.docker.container.image.v1+json",
198+
"mediaType": "application/vnd.oci.image.serialization.v1+json",
224199
"size": 7023,
225200
"digest": "sha256:b5b2b2c507a0944348e0303114d8d93aaaa081732b86451d9bce1f432a537bc7"
226201
},
227202
"layers": [
228203
{
229-
"mediaType": "application/vnd.docker.image.rootfs.diff.tar.gzip",
204+
"mediaType": "application/vnd.oci.image.rootfs.tar.gzip",
230205
"size": 32654,
231206
"digest": "sha256:e692418e4cbaf90ca69d05a66403747baa33ee08806650b51fab815ad7fc331f"
232207
},
233208
{
234-
"mediaType": "application/vnd.docker.image.rootfs.diff.tar.gzip",
209+
"mediaType": "application/vnd.oci.image.rootfs.tar.gzip",
235210
"size": 16724,
236211
"digest": "sha256:3c3a4604a545cdc127456d94e421cd355bca5b528f4a9c1905b15da2eb4a4c6b"
237212
},
238213
{
239-
"mediaType": "application/vnd.docker.image.rootfs.diff.tar.gzip",
214+
"mediaType": "application/vnd.oci.image.rootfs.tar.gzip",
240215
"size": 73109,
241216
"digest": "sha256:ec4b8955958665577945c89419d1af06b5f7636b4ac3da7f12184802ad867736"
242217
}
@@ -256,8 +231,8 @@ fall back to uploading a manifest in the old format.
256231

257232
When pulling images, clients indicate support for this new version of the
258233
manifest format by sending the
259-
`application/vnd.docker.distribution.manifest.v2+json` and
260-
`application/vnd.docker.distribution.manifest.list.v2+json` media types in an
234+
`application/vnd.oci.image.manifest.v1+json` and
235+
`application/vnd.oci.image.manifest.list.v1+json` media types in an
261236
`Accept` header when making a request to the `manifests` endpoint. Updated
262237
clients should check the `Content-Type` header to see whether the manifest
263238
returned from the endpoint is in the old format, or is an image manifest or

‎serialization.md‎

Lines changed: 1 addition & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Docker Image Specification v1.0.0
1+
# OpenContainers Image Serialization Specification
22

33
An *Image* is an ordered collection of root filesystem changes and the
44
corresponding execution parameters for use within a container runtime. This
@@ -562,12 +562,3 @@ directory which will be used as the root of a container filesystem.
562562
- Extract all contents of each archive.
563563
- Walk the directory tree once more, removing any files with the prefix
564564
`.wh.` and the corresponding file or directory named without this prefix.
565-
566-
567-
## Implementations
568-
569-
This specification is an admittedly imperfect description of an
570-
imperfectly-understood problem. The Docker project is, in turn, an attempt to
571-
implement this specification. Our goal and our execution toward it will evolve
572-
over time, but our primary concern in this specification and in our
573-
implementation is compatibility and interoperability.

0 commit comments

Comments
 (0)