You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
From the 2017-01-25 call we agreed to keep the manifest list as the
entry point for accessing objects. The index concept is only a more
generic use of the manifest-list.
#438 (comment)
This change uses the manifest-list as an index that allows
implementations to work around needing to walk/traverse the `./refs/`
directory.
As the `./refs/` directory was REQUIRED to exist, with its removal this
`index.json` is REQUIRED to be present.
This includes validating the image-layout example.
This also makes `validate-examples` automatically update `schema-fs` if
there have been changes to the JSON schema.
Obsoletes #438
Signed-off-by: Vincent Batts <[email protected]>
Copy file name to clipboardexpand all lines: image-layout.md
+99-54
Original file line number
Diff line number
Diff line change
@@ -3,47 +3,45 @@
3
3
The OCI Image Layout is a slash separated layout of OCI content-addressable blobs and [location-addressable](https://en.wikipedia.org/wiki/Content-addressable_storage#Content-addressed_vs._location-addressed) references (refs).
4
4
This layout MAY be used in a variety of different transport mechanisms: archive formats (e.g. tar, zip), shared filesystem environments (e.g. nfs), or networked file fetching (e.g. http, ftp, rsync).
5
5
6
-
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:
6
+
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-rc3/bundle.md) by:
7
7
8
8
* Following the ref to find a [manifest](manifest.md#image-manifest), possibly via a [manifest list](manifest-list.md#manifest-list)
9
9
*[Applying the filesystem layers](layer.md#applying) in the specified order
10
-
* 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)
10
+
* Converting the [image configuration](config.md) into an [OCI Runtime Specification `config.json`](https://github.com/opencontainers/runtime-spec/blob/v1.0.0-rc3/config.md)
11
11
12
12
# Content
13
13
14
-
The image layout MUST contain two top level directories:
15
-
16
-
-`blobs` contains content-addressable blobs.
17
-
A blob has no schema and should be considered opaque.
18
-
-`refs` contains [descriptors][descriptors].
19
-
Commonly pointing to an [image manifest](manifest.md#image-manifest) or an [image manifest list](manifest-list.md#oci-image-manifest-list-specification).
20
-
21
-
Both `blobs` and `refs` MAY be empty.
22
-
23
-
The image layout MUST also contain an `oci-layout` file:
24
-
25
-
- It MUST be a JSON object
26
-
- It MUST contain an `imageLayoutVersion` field
27
-
- The `imageLayoutVersion` value will align with the OCI Image Specification version at the time changes to the layout are made, and will pin a given version until changes to the layout are required
28
-
- It MAY include additional fields
14
+
The image layout is as follows:
15
+
16
+
-`blobs` directory
17
+
- Contains content-addressable blobs
18
+
- A blob has no schema and should be considered opaque
19
+
- Directory MUST exist and MAY be empty
20
+
- See [blobs](#blobs) section
21
+
-`oci-layout` file
22
+
- It MUST exist
23
+
- It MUST be a JSON object
24
+
- It MUST contain an `imageLayoutVersion` field
25
+
- See [oci-layout file](#oci-layout-file) section
26
+
- It MAY include additional fields
27
+
-`index.json` file
28
+
- It MUST exist
29
+
- It MUST be a JSON object
30
+
- It MUST have the base properties of [manifest-list](manifest-list.md).
Object names in the `refs` subdirectories MUST NOT include characters outside of the set of "A" to "Z", "a" to "z", "0" to "9", the hyphen `-`, the dot `.`, and the underscore `_`.
59
-
60
-
No semantic restriction is given for object names in the `refs` subdirectory.
61
-
Each object in the `refs` subdirectory MUST be of type `application/vnd.oci.descriptor.v1+json`.
62
-
In general the `mediaType` of this [descriptor][descriptors] object will be either `application/vnd.oci.image.manifest.list.v1+json` or `application/vnd.oci.image.manifest.v1+json` although future versions of the spec MAY use a different mediatype.
63
-
64
-
**Implementor's Note:**
65
-
A common use case of refs is representing "tags" for a container image.
66
-
For example, an image may have a tag for different versions or builds of the software.
67
-
In the wild you often see "tags" like "v1.0.0-vendor.0", "2.0.0-debug", etc.
68
-
Those tags will often be represented in an image-layout repository with matching refs names like "v1.0.0-vendor.0", "2.0.0-debug", etc.
69
-
70
-
### Example Ref
71
-
72
-
This is an example `v1.0` ref with a manifest-list descriptor:
This JSON object serves as a marker for the base of an Open Container Image Layout and to provide the version of the image-layout in use.
133
+
The `imageLayoutVersion` value will align with the OCI Image Specification version at the time changes to the layout are made, and will pin a given version until changes to the image layout are required.
134
+
135
+
### oci-layout Example
136
+
137
+
```json
138
+
{
139
+
"imageLayoutVersion": "1.0.0"
140
+
}
141
+
```
142
+
143
+
## index.json file
144
+
145
+
This REQUIRED file is the entry point for references and descriptors of the image-layout.
146
+
The [manifest-list](manifest-list.md) is a multi-descriptor entry point.
147
+
148
+
This index provides an established path (`/index.json`) to have an entry point for an image-layout and to discover auxiliary descriptors.
149
+
150
+
No semantic restriction is given for the "org.opencontainers.ref.name" annotation of descriptors.
151
+
In general the `mediaType` of each [descriptor][descriptors] object in the `manifests` field will be either `application/vnd.oci.image.manifest.list.v1+json` or `application/vnd.oci.image.manifest.v1+json`
152
+
Future versions of the spec MAY use a different mediatype (i.e. a new versioned format).
153
+
An encountered `mediaType` that is unknown SHOULD be safely ignored.
154
+
155
+
156
+
**Implementor's Note:**
157
+
A common use case of descriptors with a "org.opencontainers.ref.name" annotation is representing a "tag" for a container image.
158
+
For example, an image may have a tag for different versions or builds of the software.
159
+
In the wild you often see "tags" like "v1.0.0-vendor.0", "2.0.0-debug", etc.
160
+
Those tags will often be represented in an image-layout repository with matching "org.opencontainers.ref.name" annotations like "v1.0.0-vendor.0", "2.0.0-debug", etc.
Copy file name to clipboardexpand all lines: manifest-list.md
+4-2
Original file line number
Diff line number
Diff line change
@@ -11,7 +11,9 @@ For the media type(s) that this document is compatible with, see the [matrix][ma
11
11
-**`schemaVersion`***int*
12
12
13
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.
14
+
For this version of the specification, this MUST be `2` to ensure backward compatibility with older versions of Docker.
15
+
The value of this field will not change.
16
+
This field MAY be removed in a future version of the specification.
15
17
16
18
-**`mediaType`***string*
17
19
@@ -103,5 +105,5 @@ For the media type(s) that this document is compatible with, see the [matrix][ma
0 commit comments