diff --git a/image-layout.md b/image-layout.md new file mode 100644 index 000000000..f52fa0fb7 --- /dev/null +++ b/image-layout.md @@ -0,0 +1,45 @@ +## Open Container Initiative Image Layout Specification + +The OCI Image Layout is a slash separated layout of OCI content-addressable +This layout MAY be used in a variety of different transport mechanisms from archive formats (e.g. tar, zip) or used in shared filesystem environments (e.g. nfs) or in networked file fetching systems (e.g. http, ftp, rsync). +Given an image layout a tool can convert a given ref into a runnable OCI Image Format by finding an appopriate manifest from the manifest list, unpacking the filesystem serializations in the correct order, and then converting the image configuration into an OCI Runtime config.json. + +The image layout has two top level directories: + +- "blobs" contains content-addressable blobs +- "refs" contains descriptors pointing to an image manifest list + +This is an example image layout: + +``` +$ cd example.com/app/ +$ find . +. +./blobs +./blobs/sha256:afff3924849e458c5ef237db5f89539274d5e609db5db935ed3959c90f1f2d51 +./blobs/sha256:5b0bcabd1ed22e9fb1310cf6c2dec7cdef19f0ad69efa1f392e94a4333501270 +./blobs/sha256:e692418e4cbaf90ca69d05a66403747baa33ee08806650b51fab815ad7fc331f +./refs +./refs/v1.0 +./refs/v1.1 +``` + +The blobs directory MAY contain objects which are not referenced by any of the refs. +Each object in the refs subdirectory MUST be of type `application/vnd.oci.descriptor.v1+json`. +And the `mediatype` of this descriptor object SHOULD be `application/vnd.oci.image.manifest.list.v1+json` although future versions of the spec may use a different mediatype. + +This illustrates the expected contents of a given ref and the manifest list it points to. + +``` +$ cat ./refs/v1.0 +{"size": 4096, "digest": "sha256:afff3924849e458c5ef237db5f89539274d5e609db5db935ed3959c90f1f2d51", "mediatype": "application/vnd.oci.image.manifest.list.v1+json"} +``` +``` +$ cat ./blobs/sha256:afff3924849e458c5ef237db5f89539274d5e609db5db935ed3959c90f1f2d51 +{ + "schemaVersion": 2, + "mediaType": "application/vnd.oci.image.manifest.list.v1+json", + "manifests": [ + { +... +```