1## OCI Image Layout Specification
2
3* The OCI Image Layout is directory structure for OCI content-addressable blobs and [location-addressable](https://en.wikipedia.org/wiki/Content-addressable_storage#Content-addressed_vs._location-addressed) references (refs).
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
6Given 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/bundle.md) by:
7
8* Following the ref to find a [manifest](manifest.md#image-manifest), possibly via an [image index](image-index.md)
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/config.md)
11
12# Content
13
14The 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 an [image index](image-index.md) JSON object.
30    - See [index.json](#indexjson-file) section
31
32## Example Layout
33
34This is an example image layout:
35
36```
37$ cd example.com/app/
38$ find . -type f
39./index.json
40./oci-layout
41./blobs/sha256/3588d02542238316759cbf24502f4344ffcc8a60c803870022f335d1390c13b4
42./blobs/sha256/4b0bc1c4050b03c95ef2a8e36e25feac42fd31283e8c30b3ee5df6b043155d3c
43./blobs/sha256/7968321274dc6b6171697c33df7815310468e694ac5be0ec03ff053bb135e768
44```
45
46Blobs are named by their contents:
47
48```
49$ shasum -a 256 ./blobs/sha256/afff3924849e458c5ef237db5f89539274d5e609db5db935ed3959c90f1f2d51
50afff3924849e458c5ef237db5f89539274d5e609db5db935ed3959c90f1f2d51 ./blobs/sha256/afff3924849e458c5ef237db5f89539274d5e609db5db935ed3959c90f1f2d51
51```
52
53## Blobs
54
55* Object names in the `blobs` subdirectories are composed of a directory for each hash algorithm, the children of which will contain the actual content.
56* The content of `blobs/<alg>/<encoded>` MUST match the digest `<alg>:<encoded>` (referenced per [descriptor](descriptor.md#digests)). For example, the content of `blobs/sha256/da39a3ee5e6b4b0d3255bfef95601890afd80709` MUST match the digest `sha256:da39a3ee5e6b4b0d3255bfef95601890afd80709`.
57* The character set of the entry name for `<alg>` and `<encoded>` MUST match the respective grammar elements described in [descriptor](descriptor.md#digests).
58* The blobs directory MAY contain blobs which are not referenced by any of the [refs](#indexjson-file).
59* The blobs directory MAY be missing referenced blobs, in which case the missing blobs SHOULD be fulfilled by an external blob store.
60
61### Example Blobs
62
63```
64$ cat ./blobs/sha256/9b97579de92b1c195b85bb42a11011378ee549b02d7fe9c17bf2a6b35d5cb079 | jq
65{
66  "schemaVersion": 2,
67  "manifests": [
68    {
69      "mediaType": "application/vnd.oci.image.manifest.v1+json",
70      "size": 7143,
71      "digest": "sha256:afff3924849e458c5ef237db5f89539274d5e609db5db935ed3959c90f1f2d51",
72      "platform": {
73        "architecture": "ppc64le",
74        "os": "linux"
75      }
76    },
77...
78```
79
80```
81$ cat ./blobs/sha256/afff3924849e458c5ef237db5f89539274d5e609db5db935ed3959c90f1f2d51 | jq
82{
83  "schemaVersion": 2,
84  "config": {
85    "mediaType": "application/vnd.oci.image.config.v1+json",
86    "size": 7023,
87    "digest": "sha256:5b0bcabd1ed22e9fb1310cf6c2dec7cdef19f0ad69efa1f392e94a4333501270"
88  },
89  "layers": [
90    {
91      "mediaType": "application/vnd.oci.image.layer.v1.tar+gzip",
92      "size": 32654,
93      "digest": "sha256:9834876dcfb05cb167a5c24953eba58c4ac89b1adf57f28f2f9d09af107ee8f0"
94    },
95...
96```
97
98```
99$ cat ./blobs/sha256/5b0bcabd1ed22e9fb1310cf6c2dec7cdef19f0ad69efa1f392e94a4333501270 | jq
100{
101  "architecture": "amd64",
102  "author": "Alyssa P. Hacker <alyspdev@example.com>",
103  "config": {
104    "Hostname": "8dfe43d80430",
105    "Domainname": "",
106    "User": "",
107    "AttachStdin": false,
108    "AttachStdout": false,
109    "AttachStderr": false,
110    "Tty": false,
111    "OpenStdin": false,
112    "StdinOnce": false,
113    "Env": [
114      "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
115    ],
116    "Cmd": null,
117    "Image": "sha256:6986ae504bbf843512d680cc959484452034965db15f75ee8bdd1b107f61500b",
118...
119```
120
121```
122$ cat ./blobs/sha256/9834876dcfb05cb167a5c24953eba58c4ac89b1adf57f28f2f9d09af107ee8f0
123[gzipped tar stream]
124```
125
126## oci-layout file
127
128This 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.
129The `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.
130This section defines the `application/vnd.oci.layout.header.v1+json` [media type](media-types.md).
131
132### oci-layout Example
133
134```json,title=OCI%20Layout&mediatype=application/vnd.oci.layout.header.v1%2Bjson
135{
136    "imageLayoutVersion": "1.0.0"
137}
138```
139
140## index.json file
141
142This REQUIRED file is the entry point for references and descriptors of the image-layout.
143The [image index](image-index.md) is a multi-descriptor entry point.
144
145This index provides an established path (`/index.json`) to have an entry point for an image-layout and to discover auxiliary descriptors.
146
147* No semantic restriction is given for the "org.opencontainers.image.ref.name" annotation of descriptors.
148* In general the `mediaType` of each [descriptor][descriptors] object in the `manifests` field will be either `application/vnd.oci.image.index.v1+json` or `application/vnd.oci.image.manifest.v1+json`.
149* Future versions of the spec MAY use a different mediatype (i.e. a new versioned format).
150* An encountered `mediaType` that is unknown SHOULD be safely ignored.
151
152
153**Implementor's Note:**
154A common use case of descriptors with a "org.opencontainers.image.ref.name" annotation is representing a "tag" for a container image.
155For example, an image may have a tag for different versions or builds of the software.
156In the wild you often see "tags" like "v1.0.0-vendor.0", "2.0.0-debug", etc.
157Those tags will often be represented in an image-layout repository with matching "org.opencontainers.image.ref.name" annotations like "v1.0.0-vendor.0", "2.0.0-debug", etc.
158
159
160### Index Example
161
162```json,title=Image%20Index&mediatype=application/vnd.oci.image.index.v1%2Bjson
163{
164  "schemaVersion": 2,
165  "manifests": [
166    {
167      "mediaType": "application/vnd.oci.image.index.v1+json",
168      "size": 7143,
169      "digest": "sha256:0228f90e926ba6b96e4f39cf294b2586d38fbb5a1e385c05cd1ee40ea54fe7fd",
170      "annotations": {
171        "org.opencontainers.image.ref.name": "stable-release"
172      }
173    },
174    {
175      "mediaType": "application/vnd.oci.image.manifest.v1+json",
176      "size": 7143,
177      "digest": "sha256:e692418e4cbaf90ca69d05a66403747baa33ee08806650b51fab815ad7fc331f",
178      "platform": {
179        "architecture": "ppc64le",
180        "os": "linux"
181      },
182      "annotations": {
183        "org.opencontainers.image.ref.name": "v1.0"
184      }
185    },
186    {
187      "mediaType": "application/xml",
188      "size": 7143,
189      "digest": "sha256:b3d63d132d21c3ff4c35a061adf23cf43da8ae054247e32faa95494d904a007e",
190      "annotations": {
191        "org.freedesktop.specifications.metainfo.version": "1.0",
192        "org.freedesktop.specifications.metainfo.type": "AppStream"
193      }
194    }
195  ],
196  "annotations": {
197    "com.example.index.revision": "r124356"
198  }
199}
200```
201
202This illustrates an index that provides two named manifest references and an auxiliary mediatype for this image layout.
203
204
205[descriptors]: ./descriptor.md
206