Skip to content

Commit 44ce8a7

Browse files
jonboullejonboulle
authored
Merge pull request opencontainers#365 from jonboulle/cleanup
*: split manifest and manifest list documents
2 parents 527b53f + 07171f3 commit 44ce8a7

File tree

7 files changed

+135
-127
lines changed

7 files changed

+135
-127
lines changed

‎Makefile‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,8 @@ DOC_FILES := \
2929
image-layout.md \
3030
layer.md \
3131
config.md \
32-
manifest.md
32+
manifest.md \
33+
manifest-list.md
3334

3435
FIGURE_FILES := \
3536
img/media-types.png

‎README.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,8 @@ The OCI Image Format project creates and maintains the software shipping contain
1212
- [Image Layout](image-layout.md)
1313
- [Filesystem Layers](layer.md)
1414
- [Image Configuration](config.md)
15-
- [Manifests and Manifest Lists](manifest.md)
15+
- [Image Manifest](manifest.md)
16+
- [Image Manifest List](manifest-list.md)
1617

1718
## Overview
1819

‎image-layout.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ This layout MAY be used in a variety of different transport mechanisms: archive
55

66
Given an image layout and a ref, a tool can create an [OCI Runtime Specification bundle](https://github.com/opencontainers/runtime-spec/blob/v1.0.0-rc2/bundle.md) by:
77

8-
* Following the ref to find a [manifest](manifest.md#image-manifest), possibly via a [manifest list](manifest.md#manifest-list)
8+
* Following the ref to find a [manifest](manifest.md#image-manifest), possibly via a [manifest list](manifest-list.md#manifest-list)
99
* [Applying the filesystem layers](layers.md#applying) in the specified order
1010
* Converting the [image configuration](config.md) into an [OCI Runtime Specification `config.json`](https://github.com/opencontainers/runtime-spec/blob/v1.0.0-rc2/config.md)
1111

‎manifest-list.md‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
# OCI Image Manifest List Specification
2+
3+
The manifest list is a higher-level manifest which points to specific [image manifests](manifest.md) for one or more platforms.
4+
While the use of a manifest list is OPTIONAL for image providers, image consumers SHOULD be prepared to process them.
5+
A client will distinguish a manifest list from an image manifest based on the Content-Type returned in the HTTP response.
6+
7+
This section defines the `application/vnd.oci.image.manifest.list.v1+json` [media type](media-types.md).
8+
9+
## *Manifest List* Property Descriptions
10+
11+
- **`schemaVersion`** *int*
12+
13+
This REQUIRED property specifies the image manifest schema version.
14+
For this version of the specification, this MUST be `2` to ensure backward compatibility with older versions of Docker. The value of this field will not change. This field MAY be removed in a future version of the specification.
15+
16+
- **`mediaType`** *string*
17+
18+
This REQUIRED property contains the media type of the manifest list.
19+
For this version of the specification, this MUST be set to `application/vnd.oci.image.manifest.list.v1+json`.
20+
For the media type(s) that this is compatible with see the [matrix](media-types.md#compatibility-matrix).
21+
22+
- **`manifests`** *array*
23+
24+
This REQUIRED property contains a list of manifests for specific platforms.
25+
While the property MUST be present, the size of the array MAY be zero.
26+
27+
Each object in the manifest is a [descriptor](descriptor.md) with the following additional properties and restrictions:
28+
29+
- **`mediaType`** *object*
30+
31+
This [descriptor property](descriptor.md#properties) has additional restrictions for `manifests`.
32+
Implementations MUST support at least the following media types:
33+
34+
- [`application/vnd.oci.image.manifest.v1+json`](manifest.md)
35+
36+
Manifest lists concerned with portability SHOULD use one of the above media types.
37+
38+
- **`platform`** *object*
39+
40+
This REQUIRED property describes the platform which the image in the manifest runs on.
41+
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)
42+
43+
- **`architecture`** *string*
44+
45+
This REQUIRED property specified the CPU architecture, for example `amd64` or `ppc64le`.
46+
47+
- **`os`** *string*
48+
49+
This REQUIRED property specifies the operating system, for example `linux` or `windows`.
50+
51+
- **`os.version`** *string*
52+
53+
This OPTIONAL property specifies the operating system version, for example `10.0.10586`.
54+
55+
- **`os.features`** *array*
56+
57+
This OPTIONAL property specifies an array of strings, each specifying a mandatory OS feature (for example on Windows `win32k`).
58+
59+
- **`variant`** *string*
60+
61+
This OPTIONAL property specifies the variant of the CPU, for example `armv6l` to specify a particular CPU variant of the ARM CPU.
62+
63+
- **`features`** *array*
64+
65+
This OPTIONAL property specifies an array of strings, each specifying a mandatory CPU feature (for example `sse4` or `aes`).
66+
67+
- **`annotations`** *string-string map*
68+
69+
This OPTIONAL property contains arbitrary metadata for the manifest list.
70+
Annotations MUST be a key-value map where both the key and value MUST be strings.
71+
While the value MUST be present, it MAY be an empty string.
72+
Keys MUST be unique within this map, and best practice is to namespace the keys.
73+
Keys SHOULD be named using a reverse domain notation - e.g. `com.example.myKey`.
74+
Keys using the `org.opencontainers` namespace are reserved and MUST NOT be used by other specifications.
75+
If there are no annotations then this property MUST either be absent or be an empty map.
76+
Implementations that are reading/processing manifest lists MUST NOT generate an error if they encounter an unknown annotation key.
77+
78+
See [Pre-Defined Annotation Keys](manifest.md#pre-defined-annotation-keys).
79+
80+
### Extensibility
81+
Implementations that are reading/processing manifest lists MUST NOT generate an error if they encounter an unknown property.
82+
Instead they MUST ignore unknown properties.
83+
84+
## Example Manifest List
85+
86+
*Example showing a simple manifest list pointing to image manifests for two platforms:*
87+
```json,title=Manifest%20List&mediatype=application/vnd.oci.image.manifest.list.v1%2Bjson
88+
{
89+
"schemaVersion": 2,
90+
"mediaType": "application/vnd.oci.image.manifest.list.v1+json",
91+
"manifests": [
92+
{
93+
"mediaType": "application/vnd.oci.image.manifest.v1+json",
94+
"size": 7143,
95+
"digest": "sha256:e692418e4cbaf90ca69d05a66403747baa33ee08806650b51fab815ad7fc331f",
96+
"platform": {
97+
"architecture": "ppc64le",
98+
"os": "linux"
99+
}
100+
},
101+
{
102+
"mediaType": "application/vnd.oci.image.manifest.v1+json",
103+
"size": 7682,
104+
"digest": "sha256:5b0bcabd1ed22e9fb1310cf6c2dec7cdef19f0ad69efa1f392e94a4333501270",
105+
"platform": {
106+
"architecture": "amd64",
107+
"os": "linux",
108+
"features": [
109+
"sse4"
110+
]
111+
}
112+
}
113+
],
114+
"annotations": {
115+
"com.example.key1": "value1",
116+
"com.example.key2": "value2"
117+
}
118+
}
119+
```

‎manifest.md‎

Lines changed: 4 additions & 121 deletions
Original file line numberDiff line numberDiff line change
@@ -3,131 +3,14 @@
33
There are three main goals of the Image Manifest Specification.
44
The first goal is content-addressable images, by supporting an image model where the image's configuration can be hashed to generate a unique ID for the image and its components.
55
The second goal is to allow multi-architecture images, through a "fat manifest" which references image manifests for platform-specific versions of an image.
6-
The third goal is to be translatable to the [OpenContainers/runtime-spec](https://github.com/opencontainers/runtime-spec)
6+
In OCI, this is codified in a [Manifest List](manifest-list.md).
7+
The third goal is to be translatable to the [OCI Runtime Specification](https://github.com/opencontainers/runtime-spec).
78

8-
This section defines the `application/vnd.oci.image.manifest.list.v1+json` and `application/vnd.oci.image.manifest.v1+json` [media types](media-types.md).
9-
10-
# Manifest List
11-
12-
The manifest list is the "fat manifest" which points to specific image manifests for one or more platforms.
13-
While the use of a manifest list is OPTIONAL for image providers, image consumers SHOULD be prepared to process them.
14-
A client will distinguish a manifest list from an image manifest based on the Content-Type returned in the HTTP response.
15-
16-
## *Manifest List* Property Descriptions
17-
18-
- **`schemaVersion`** *int*
19-
20-
This REQUIRED property specifies the image manifest schema version.
21-
For this version of the specification, this MUST be `2` to ensure backward compatibility with older versions of Docker. The value of this field will not change. This field MAY be removed in a future version of the specification.
22-
23-
- **`mediaType`** *string*
24-
25-
This REQUIRED property contains the media type of the manifest list.
26-
For this version of the specification, this MUST be set to `application/vnd.oci.image.manifest.list.v1+json`.
27-
For the media type(s) that this is compatible with see the [matrix](media-types.md#compatibility-matrix).
28-
29-
- **`manifests`** *array*
30-
31-
This REQUIRED property contains a list of manifests for specific platforms.
32-
While the property MUST be present, the size of the array MAY be zero.
33-
34-
Each object in the manifest is a [descriptor](descriptor.md) with the following additional properties and restrictions:
35-
36-
- **`mediaType`** *object*
37-
38-
This [descriptor property](descriptor.md#properties) has additional restrictions for `manifests`.
39-
Implementations MUST support at least the following media types:
40-
41-
- [`application/vnd.oci.image.manifest.v1+json`](#image-manifest)
42-
43-
Manifest lists concerned with portability SHOULD use one of the above media types.
44-
45-
- **`platform`** *object*
46-
47-
This REQUIRED property describes the platform which the image in the manifest runs on.
48-
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)
49-
50-
- **`architecture`** *string*
51-
52-
This REQUIRED property specified the CPU architecture, for example `amd64` or `ppc64le`.
53-
54-
- **`os`** *string*
55-
56-
This REQUIRED property specifies the operating system, for example `linux` or `windows`.
57-
58-
- **`os.version`** *string*
59-
60-
This OPTIONAL property specifies the operating system version, for example `10.0.10586`.
61-
62-
- **`os.features`** *array*
63-
64-
This OPTIONAL property specifies an array of strings, each specifying a mandatory OS feature (for example on Windows `win32k`).
65-
66-
- **`variant`** *string*
67-
68-
This OPTIONAL property specifies the variant of the CPU, for example `armv6l` to specify a particular CPU variant of the ARM CPU.
69-
70-
- **`features`** *array*
71-
72-
This OPTIONAL property specifies an array of strings, each specifying a mandatory CPU feature (for example `sse4` or `aes`).
73-
74-
- **`annotations`** *string-string map*
75-
76-
This OPTIONAL property contains arbitrary metadata for the manifest list.
77-
Annotations MUST be a key-value map where both the key and value MUST be strings.
78-
While the value MUST be present, it MAY be an empty string.
79-
Keys MUST be unique within this map, and best practice is to namespace the keys.
80-
Keys SHOULD be named using a reverse domain notation - e.g. `com.example.myKey`.
81-
Keys using the `org.opencontainers` namespace are reserved and MUST NOT be used by other specifications.
82-
If there are no annotations then this property MUST either be absent or be an empty map.
83-
Implementations that are reading/processing manifest lists MUST NOT generate an error if they encounter an unknown annotation key.
84-
85-
See [Pre-Defined Annotation Keys](#pre-defined-annotation-keys).
86-
87-
### Extensibility
88-
Implementations that are reading/processing manifest lists MUST NOT generate an error if they encounter an unknown property.
89-
Instead they MUST ignore unknown properties.
90-
91-
## Example Manifest List
92-
93-
*Example showing a simple manifest list pointing to image manifests for two platforms:*
94-
```json,title=Manifest%20List&mediatype=application/vnd.oci.image.manifest.list.v1%2Bjson
95-
{
96-
"schemaVersion": 2,
97-
"mediaType": "application/vnd.oci.image.manifest.list.v1+json",
98-
"manifests": [
99-
{
100-
"mediaType": "application/vnd.oci.image.manifest.v1+json",
101-
"size": 7143,
102-
"digest": "sha256:e692418e4cbaf90ca69d05a66403747baa33ee08806650b51fab815ad7fc331f",
103-
"platform": {
104-
"architecture": "ppc64le",
105-
"os": "linux"
106-
}
107-
},
108-
{
109-
"mediaType": "application/vnd.oci.image.manifest.v1+json",
110-
"size": 7682,
111-
"digest": "sha256:5b0bcabd1ed22e9fb1310cf6c2dec7cdef19f0ad69efa1f392e94a4333501270",
112-
"platform": {
113-
"architecture": "amd64",
114-
"os": "linux",
115-
"features": [
116-
"sse4"
117-
]
118-
}
119-
}
120-
],
121-
"annotations": {
122-
"com.example.key1": "value1",
123-
"com.example.key2": "value2"
124-
}
125-
}
126-
```
9+
This section defines the `application/vnd.oci.image.manifest.v1+json` [media type](media-types.md).
12710

12811
# Image Manifest
12912

130-
Unlike the [Manifest List](#manifest-list), which contains information about a set of images that can span a variety of architectures and operating systems, an image manifest provides a configuration and set of layers for a single container image for a specific architecture and operating system.
13+
Unlike the [Manifest List](manifest-list.md), which contains information about a set of images that can span a variety of architectures and operating systems, an image manifest provides a configuration and set of layers for a single container image for a specific architecture and operating system.
13114

13215
## *Image Manifest* Property Descriptions
13316

‎media-types.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3,9 +3,9 @@
33
The following media types identify the formats described here and their referenced resources:
44

55
- `application/vnd.oci.descriptor.v1+json`: [Content Descriptor](descriptor.md)
6-
- `application/vnd.oci.image.manifest.list.v1+json`: [Manifest list](manifest.md#manifest-list)
7-
- `application/vnd.oci.image.manifest.v1+json`: [Image manifest format](manifest.md#image-manifest)
8-
- `application/vnd.oci.image.config.v1+json`: [Image config JSON](config.md)
6+
- `application/vnd.oci.image.manifest.list.v1+json`: [Manifest list](manifest-list.md#manifest-list)
7+
- `application/vnd.oci.image.manifest.v1+json`: [Image manifest](manifest.md#image-manifest)
8+
- `application/vnd.oci.image.config.v1+json`: [Image config](config.md)
99
- `application/vnd.oci.image.layer.v1.tar+gzip`: ["Layer", as a gzipped tar archive](layer.md)
1010
- `application/vnd.oci.image.layer.nondistributable.v1.tar+gzip`: ["Layer", as a gzipped tar archive with distribution restrictions](layer.md#non-distributable-layers)
1111

‎schema/spec_test.go‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,10 @@ func TestValidateManifest(t *testing.T) {
4141
validate(t, "../manifest.md")
4242
}
4343

44+
func TestValidateManifestList(t *testing.T) {
45+
validate(t, "../manifest-list.md")
46+
}
47+
4448
func TestValidateConfig(t *testing.T) {
4549
validate(t, "../config.md")
4650
}

0 commit comments

Comments
 (0)