opencontainers/image-spec
1
0
Fork 0
mirror of https://github.com/opencontainers/image-spec.git synced 2025-04-18 03:24:01 +03:00
Code

Add a markdown linter and fix linting issues

Browse Source 
Signed-off-by: Brandon Mitchell <git@bmitch.net>
This commit is contained in:
Brandon Mitchell 2023-06-29 19:15:54 -04:00
parent b74f37875d
commit a6af2b480d
No known key found for this signature in database
GPG Key ID: 6E0FF28C767A8BEE
20 changed files with 436 additions and 395 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.github/PULL_REQUEST_TEMPLATE/maintainer_nomination.md vendored
View File

@ -11,11 +11,13 @@ Name of the new maintainer with GitHub username
## Justification
Highlight any work contributed by the new maintainer. Examples of contributions may be:
- Community involvement in mailing lists and meetings
- Involvement in any OCI working groups
- Contributions to any of the OCI git repositories
Other considerations may be:
- Diversity of organizations
- Time involved in the community
- Personal experience working with the new maintainer

18
.markdownlint.yml Normal file
View File

@ -0,0 +1,18 @@
# all lists use a `-`
MD004:
style: dash
# allow tabs in code blocks (for Go)
MD010:
code_blocks: false
# disable line length, prefer one sentence per line for PRs
MD013: false
# emphasis with underscore (`_emphasis_`)
MD049:
style: "underscore"
# bold with asterisk (`**bold**`)
MD050:
style: "asterisk"

12
EMERITUS.md
View File

@ -1,9 +1,11 @@
# Emeritus
We would like to acknowledge previous OCI image spec maintainers and their huge contributions to our collective success:
* Brandon Philips (@philips)
* Brendan Burns (@brendandburns)
* Jason Bouzane (@jbouzane)
* John Starks (@jstarks)
* Keyang Xie (@xiekeyang)
- Brandon Philips (@philips)
- Brendan Burns (@brendandburns)
- Jason Bouzane (@jbouzane)
- John Starks (@jstarks)
- Keyang Xie (@xiekeyang)
We thank these members for their service to the OCI community.

10
HACKING.md
View File

@ -10,8 +10,8 @@ This spec includes several Go packages, and a command line tool considered to be
Prerequisites:
* Go - current release only, earlier releases are not supported
* make
- Go - current release only, earlier releases are not supported
- make
The following make targets are relevant for any work involving the Go packages.
@ -43,7 +43,7 @@ This target auto-formats all JSON files in the `schema` directory using the `jq`
Prerequisites:
* [jq][jq] >=1.5
- [jq][jq] >=1.5
Invocation:
@ -57,7 +57,7 @@ This target generates a PDF/HTML version of the OCI image specification.
Prerequisites:
* [Docker][docker]
- [Docker][docker]
Invocation:
@ -91,7 +91,7 @@ This target generates PNG image files from DOT source files in the `img` directo
Prerequisites:
* [graphviz][graphviz]
- [graphviz][graphviz]
Invocation:

16
Makefile
View File

@ -41,6 +41,8 @@ DOC_FILES := \
FIGURE_FILES := \
img/media-types.png
MARKDOWN_LINT_VER?=v0.8.1
TOOLS := gitvalidation
default: check-license lint test
@ -81,10 +83,20 @@ check-license: ## check license headers in source files
@./.tool/check-license
.PHONY: lint
lint: .install.lint ## lint check of Go files using golangci-lint
@echo "checking lint"
.PHONY: lint
lint: lint-go lint-md ## Run all linters
.PHONY: lint-go
lint-go: .install.lint ## lint check of Go files using golangci-lint
@echo "checking Go lint"
@GO111MODULE=on $(GOPATH)/bin/golangci-lint run
.PHONY: lint-md
lint-md: ## Run linting for markdown
docker run --rm -v "$(PWD):/workdir:ro" docker.io/davidanson/markdownlint-cli2:$(MARKDOWN_LINT_VER) \
**/*.md "#vendor"
.PHONY: test
test: ## run the unit tests
go test -race -cover $(shell go list ./... | grep -v /vendor/)

40
README.md
View File

@ -1,9 +1,8 @@
# OCI Image Format Specification
<div>
<a href="https://travis-ci.org/opencontainers/image-spec">
<img src="https://travis-ci.org/opencontainers/image-spec.svg?branch=master"></img>
</a>
</div>
![GitHub Actions for Docs and Linting](https://img.shields.io/github/actions/workflow/status/opencontainers/image-spec/docs-and-linting.yml?branch=main&label=GHA%20docs%20and%20linting)
![License](https://img.shields.io/github/license/opencontainers/image-spec)
[![Go Reference](https://pkg.go.dev/badge/github.com/opencontainers/image-spec.svg)](https://pkg.go.dev/github.com/opencontainers/image-spec)
The OCI Image Format project creates and maintains the software shipping container image format spec (OCI Image Format).
@ -28,8 +27,8 @@ At this point the OCI Runtime Bundle would be run by an OCI Runtime.
This entire workflow supports the UX that users have come to expect from container engines like Docker and rkt: primarily, the ability to run an image with no additional arguments:
* docker run example.com/org/app:v1.0.0
* rkt run example.com/org/app,version=v1.0.0
- docker run example.com/org/app:v1.0.0
- rkt run example.com/org/app,version=v1.0.0
To support this UX the OCI Image Format contains sufficient information to launch the application on the target platform (e.g. command, arguments, environment variables, etc).
@ -51,14 +50,14 @@ Find more [FAQ on the OCI site](https://www.opencontainers.org/faq).
The [GitHub milestones](https://github.com/opencontainers/image-spec/milestones) lay out the path to the future improvements.
# Contributing
## Contributing
Development happens on GitHub for the spec.
Issues are used for bugs and actionable items and longer discussions can happen on the [mailing list](#mailing-list).
The specification and code is licensed under the Apache 2.0 license found in the `LICENSE` file of this repository.
## Discuss your design
### Discuss your design
The project welcomes submissions, but please let everyone know what you are working on.
@ -69,33 +68,33 @@ It also guarantees that the design is sound before code is written; a GitHub pul
Typos and grammatical errors can go straight to a pull-request.
When in doubt, start on the [mailing-list](#mailing-list).
## Meetings
### Meetings
Please see the [OCI org repository README](https://github.com/opencontainers/org#meetings) for the most up-to-date information on OCI contributor and maintainer meeting schedules.
Please see the [OCI org repository README](https://github.com/opencontainers/org#meetings) for the most up-to-date information on OCI contributor and maintainer meeting schedules.
You can also find links to meeting agendas and minutes for all prior meetings.
## Mailing List
### Mailing List
You can subscribe and join the mailing list on [Google Groups](https://groups.google.com/a/opencontainers.org/forum/#!forum/dev).
## IRC
### IRC
OCI discussion happens on #opencontainers on Freenode ([logs][irc-logs]).
## Markdown style
### Markdown style
To keep consistency throughout the Markdown files in the Open Container spec all files should be formatted one sentence per line.
This fixes two things: it makes diffing easier with git and it resolves fights about line wrapping length.
For example, this paragraph will span three lines in the Markdown source.
## Git commit
### Git commit
### Sign your work
#### Sign your work
The sign-off is a simple line at the end of the explanation for the patch, which certifies that you wrote it or otherwise have the right to pass it on as an open-source patch.
The rules are pretty simple: if you can certify the below (from [developercertificate.org](https://developercertificate.org/)):
```
```text
Developer Certificate of Origin
Version 1.1
@ -136,7 +135,9 @@ By making a contribution to this project, I certify that:
then you just add a line to every git commit message:
Signed-off-by: Joe Smith <joe@gmail.com>
```text
Signed-off-by: Joe Smith <joe@gmail.com>
```
using your real name (sorry, no pseudonyms or anonymous contributions.)
@ -154,9 +155,8 @@ Read more on [How to Write a Git Commit Message](https://chris.beams.io/posts/gi
5. Use the imperative mood in the subject line
6. Wrap the body at 72 characters
7. Use the body to explain what and why vs. how
* If there was important/useful/essential conversation or information, copy or include a reference
- If there was important/useful/essential conversation or information, copy or include a reference
8. When possible, one keyword to scope the change in the subject (i.e. "README: ...", "runtime: ...")
[code-of-conduct]: https://github.com/opencontainers/org/blob/master/CODE_OF_CONDUCT.md
[irc-logs]: http://ircbot.wl.linuxfoundation.org/eavesdrop/%23opencontainers/

76
RELEASES.md
View File

@ -20,8 +20,8 @@ They may not propose a v1.0.0-rc3 until the v1.0.0-rc2 is accepted (on the 7th i
The OCI maintains three categories of projects: specifications, applications, and conformance-testing tools.
However, specification releases have special restrictions in the [OCI charter][charter]:
* They are the target of backwards compatibility (§7.g), and
* They are subject to the OFWa patent grant (§8.d and e).
- They are the target of backwards compatibility (§7.g), and
- They are subject to the OFWa patent grant (§8.d and e).
To avoid unfortunate side effects (onerous backwards compatibility requirements or Member resignations), the following additional procedures apply to specification releases:
@ -29,24 +29,24 @@ To avoid unfortunate side effects (onerous backwards compatibility requirements
Every OCI specification project SHOULD hold meetings that involve maintainers reviewing pull requests, debating outstanding issues, and planning releases.
This meeting MUST be advertised on the project README and MAY happen on a phone call, video conference, or on IRC.
Maintainers MUST send updates to the dev@opencontainers.org with results of these meetings.
Maintainers MUST send updates to the <dev@opencontainers.org> with results of these meetings.
Before the specification reaches v1.0.0, the meetings SHOULD be weekly.
Once a specification has reached v1.0.0, the maintainers may alter the cadence, but a meeting MUST be held within four weeks of the previous meeting.
The release plans, corresponding milestones and estimated due dates MUST be published on GitHub (e.g. https://github.com/opencontainers/runtime-spec/milestones).
The release plans, corresponding milestones and estimated due dates MUST be published on GitHub (e.g. <https://github.com/opencontainers/runtime-spec/milestones>).
GitHub milestones and issues are only used for community organization and all releases MUST follow the [project governance](GOVERNANCE.md) rules and procedures.
### Timelines
Specifications have a variety of different timelines in their lifecycle.
* Pre-v1.0.0 specifications SHOULD release on a monthly cadence to garner feedback.
* Major specification releases MUST release at least three release candidates spaced a minimum of one week apart.
- Pre-v1.0.0 specifications SHOULD release on a monthly cadence to garner feedback.
- Major specification releases MUST release at least three release candidates spaced a minimum of one week apart.
This means a major release like a v1.0.0 or v2.0.0 release will take 1 month at minimum: one week for rc1, one week for rc2, one week for rc3, and one week for the major release itself.
Maintainers SHOULD strive to make zero breaking changes during this cycle of release candidates and SHOULD restart the three-candidate count when a breaking change is introduced.
For example if a breaking change is introduced in v1.0.0-rc2 then the series would end with v1.0.0-rc4 and v1.0.0.
* Minor and patch releases SHOULD be made on an as-needed basis.
- Minor and patch releases SHOULD be made on an as-needed basis.
[charter]: https://github.com/opencontainers/tob/blob/main/CHARTER.md
@ -54,25 +54,26 @@ Specifications have a variety of different timelines in their lifecycle.
Releases usually follow a few steps:
* [ ] prepare a pull-request for the release
* [ ] a commit updating `./ChangeLog`
* [ ] `git log --oneline --no-merges --decorate --name-status v1.0.1..HEAD | vim -`
* [ ] `:% s/(pr\/\(\d*\))\(.*\)/\2 (#\1)/` to move the PR to the end of line and match previous formatting
* [ ] review `(^M|^A|^D)` for impact of the commit
* [ ] group commits to `Additions:`, `Minor fixes and documentation:`, `Breaking changes:`
* [ ] delete the `(^M|^A|^D)` lines, `:%!grep -vE '(^M|^A|^D)'`
* [ ] merge multi-commit PRs (so each line has a `(#num)` suffix)
* [ ] drop hash and indent, `:'<,'> s/^\w* /^I* /`
* [ ] a commit bumping `./specs-go/version.go` to next version and empty the `VersionDev` variable
* [ ] a commit adding back the "+dev" to `VersionDev`
* [ ] send email to dev@opencontainers.org
* [ ] copy the exact commit hash for bumping the version from the pull-request (since master always stays as "-dev")
* [ ] count the PRs since last release (that this version is tracking, in the cases of multiple branching), like `git log --pretty=oneline --no-merges --decorate $priorTag..$versionBumpCommit | grep \(pr\/ | wc -l`
* [ ] get the date for a week from now, like `TZ=UTC date --date='next week'`
* [ ] OPTIONAL find a cute animal gif to attach to the email, and subsequently the release description
* [ ] subject line like `[runtime-spec VOTE] tag $versionBumpCommit as $version (closes $dateWeekFromNowUTC)`
* [ ] email body like
```
- [ ] prepare a pull-request for the release
- [ ] a commit updating `./ChangeLog`
- [ ] `git log --oneline --no-merges --decorate --name-status v1.0.1..HEAD | vim -`
- [ ] `:% s/(pr\/\(\d*\))\(.*\)/\2 (#\1)/` to move the PR to the end of line and match previous formatting
- [ ] review `(^M|^A|^D)` for impact of the commit
- [ ] group commits to `Additions:`, `Minor fixes and documentation:`, `Breaking changes:`
- [ ] delete the `(^M|^A|^D)` lines, `:%!grep -vE '(^M|^A|^D)'`
- [ ] merge multi-commit PRs (so each line has a `(#num)` suffix)
- [ ] drop hash and indent, `:'<,'> s/^\w* /^I* /`
- [ ] a commit bumping `./specs-go/version.go` to next version and empty the `VersionDev` variable
- [ ] a commit adding back the "+dev" to `VersionDev`
- [ ] send email to <dev@opencontainers.org>
- [ ] copy the exact commit hash for bumping the version from the pull-request (since master always stays as "-dev")
- [ ] count the PRs since last release (that this version is tracking, in the cases of multiple branching), like `git log --pretty=oneline --no-merges --decorate $priorTag..$versionBumpCommit | grep \(pr\/ | wc -l`
- [ ] get the date for a week from now, like `TZ=UTC date --date='next week'`
- [ ] OPTIONAL find a cute animal gif to attach to the email, and subsequently the release description
- [ ] subject line like `[runtime-spec VOTE] tag $versionBumpCommit as $version (closes $dateWeekFromNowUTC)`
- [ ] email body like
```text
Hey everyone,
There have been $numPRs PRs merged since $priorTag release (https://github.com/opencontainers/image-spec/compare/$priorTag...$versionBumpCommit).
@ -83,14 +84,15 @@ Please respond LGTM or REJECT (with reasoning).
$sig
```
* [ ] edit/update the pull-request to link to the VOTE thread, from https://groups.google.com/a/opencontainers.org/forum/#!forum/dev
* [ ] a week later, if the vote passes, merge the PR
* [ ] `git tag -s $version $versionBumpCommit`
* [ ] `git push --tags`
* [ ] produce release documents
* [ ] git checkout the release tag, like `git checkout $version`
* [ ] `make docs`
* [ ] rename the output PDF and HTML file to include version, like `mv output/oci-runtime-spec.pdf output/oci-runtime-spec-$version.pdf``
* [ ] attach these docs to the release on https://github.com/opencontainers/runtime-spec/releases
* [ ] link to the the VOTE thread and include the passing vote count
* [ ] link to the pull request that merged the release
- [ ] edit/update the pull-request to link to the VOTE thread, from <https://groups.google.com/a/opencontainers.org/forum/#!forum/dev>
- [ ] a week later, if the vote passes, merge the PR
- [ ] `git tag -s $version $versionBumpCommit`
- [ ] `git push --tags`
- [ ] produce release documents
- [ ] git checkout the release tag, like `git checkout $version`
- [ ] `make docs`
- [ ] rename the output PDF and HTML file to include version, like `mv output/oci-runtime-spec.pdf output/oci-runtime-spec-$version.pdf``
- [ ] attach these docs to the release on <https://github.com/opencontainers/runtime-spec/releases>
- [ ] link to the the VOTE thread and include the passing vote count
- [ ] link to the pull request that merged the release

72
annotations.md
View File

@ -6,51 +6,53 @@ This property contains arbitrary metadata.
## Rules
* Annotations MUST be a key-value map where both the key and value MUST be strings.
* While the value MUST be present, it MAY be an empty string.
* Keys MUST be unique within this map, and best practice is to namespace the keys.
* Keys SHOULD be named using a reverse domain notation - e.g. `com.example.myKey`.
* The prefix `org.opencontainers` is reserved for keys defined in Open Container Initiative (OCI) specifications and MUST NOT be used by other specifications and extensions.
* Keys using the `org.opencontainers.image` namespace are reserved for use in the OCI Image Specification and MUST NOT be used by other specifications and extensions, including other OCI specifications.
* If there are no annotations then this property MUST either be absent or be an empty map.
* Consumers MUST NOT generate an error if they encounter an unknown annotation key.
- Annotations MUST be a key-value map where both the key and value MUST be strings.
- While the value MUST be present, it MAY be an empty string.
- Keys MUST be unique within this map, and best practice is to namespace the keys.
- Keys SHOULD be named using a reverse domain notation - e.g. `com.example.myKey`.
- The prefix `org.opencontainers` is reserved for keys defined in Open Container Initiative (OCI) specifications and MUST NOT be used by other specifications and extensions.
- Keys using the `org.opencontainers.image` namespace are reserved for use in the OCI Image Specification and MUST NOT be used by other specifications and extensions, including other OCI specifications.
- If there are no annotations then this property MUST either be absent or be an empty map.
- Consumers MUST NOT generate an error if they encounter an unknown annotation key.
## Pre-Defined Annotation Keys
This specification defines the following annotation keys, intended for but not limited to [image index](image-index.md), image [manifest](manifest.md), and [descriptor](descriptor.md) authors.
* **org.opencontainers.image.created** date and time on which the image was built, conforming to [RFC 3339][rfc3339].
* **org.opencontainers.image.authors** contact details of the people or organization responsible for the image (freeform string)
* **org.opencontainers.image.url** URL to find more information on the image (string)
* **org.opencontainers.image.documentation** URL to get documentation on the image (string)
* **org.opencontainers.image.source** URL to get source code for building the image (string)
* **org.opencontainers.image.version** version of the packaged software
* The version MAY match a label or tag in the source code repository
* version MAY be [Semantic versioning-compatible](https://semver.org/)
* **org.opencontainers.image.revision** Source control revision identifier for the packaged software.
* **org.opencontainers.image.vendor** Name of the distributing entity, organization or individual.
* **org.opencontainers.image.licenses** License(s) under which contained software is distributed as an [SPDX License Expression][spdx-license-expression].
* **org.opencontainers.image.ref.name** Name of the reference for a target (string).
* SHOULD only be considered valid when on descriptors on `index.json` within [image layout](image-layout.md).
* Character set of the value SHOULD conform to alphanum of `A-Za-z0-9` and separator set of `-._:@/+`
* The reference must match the following [grammar](considerations.md#ebnf):
```
- **org.opencontainers.image.created** date and time on which the image was built, conforming to [RFC 3339][rfc3339].
- **org.opencontainers.image.authors** contact details of the people or organization responsible for the image (freeform string)
- **org.opencontainers.image.url** URL to find more information on the image (string)
- **org.opencontainers.image.documentation** URL to get documentation on the image (string)
- **org.opencontainers.image.source** URL to get source code for building the image (string)
- **org.opencontainers.image.version** version of the packaged software
- The version MAY match a label or tag in the source code repository
- version MAY be [Semantic versioning-compatible](https://semver.org/)
- **org.opencontainers.image.revision** Source control revision identifier for the packaged software.
- **org.opencontainers.image.vendor** Name of the distributing entity, organization or individual.
- **org.opencontainers.image.licenses** License(s) under which contained software is distributed as an [SPDX License Expression][spdx-license-expression].
- **org.opencontainers.image.ref.name** Name of the reference for a target (string).
- SHOULD only be considered valid when on descriptors on `index.json` within [image layout](image-layout.md).
- Character set of the value SHOULD conform to alphanum of `A-Za-z0-9` and separator set of `-._:@/+`
- The reference must match the following [grammar](considerations.md#ebnf):
```ebnf
ref ::= component ("/" component)*
component ::= alphanum (separator alphanum)*
alphanum ::= [A-Za-z0-9]+
separator ::= [-._:@+] | "--"
```
* **org.opencontainers.image.title** Human-readable title of the image (string)
* **org.opencontainers.image.description** Human-readable description of the software packaged in the image (string)
* **org.opencontainers.image.base.digest** [Digest](descriptor.md#digests) of the image this image is based on (string)
* This SHOULD be the immediate image sharing zero-indexed layers with the image, such as from a Dockerfile `FROM` statement.
* This SHOULD NOT reference any other images used to generate the contents of the image (e.g., multi-stage Dockerfile builds).
* **org.opencontainers.image.base.name** Image reference of the image this image is based on (string)
* This SHOULD be image references in the format defined by [distribution/distribution][distribution-reference].
* This SHOULD be a fully qualified reference name, without any assumed default registry. (e.g., `registry.example.com/my-org/my-image:tag` instead of `my-org/my-image:tag`).
* This SHOULD be the immediate image sharing zero-indexed layers with the image, such as from a Dockerfile `FROM` statement.
* This SHOULD NOT reference any other images used to generate the contents of the image (e.g., multi-stage Dockerfile builds).
* If the `image.base.name` annotation is specified, the `image.base.digest` annotation SHOULD be the digest of the manifest referenced by the `image.ref.name` annotation.
- **org.opencontainers.image.title** Human-readable title of the image (string)
- **org.opencontainers.image.description** Human-readable description of the software packaged in the image (string)
- **org.opencontainers.image.base.digest** [Digest](descriptor.md#digests) of the image this image is based on (string)
- This SHOULD be the immediate image sharing zero-indexed layers with the image, such as from a Dockerfile `FROM` statement.
- This SHOULD NOT reference any other images used to generate the contents of the image (e.g., multi-stage Dockerfile builds).
- **org.opencontainers.image.base.name** Image reference of the image this image is based on (string)
- This SHOULD be image references in the format defined by [distribution/distribution][distribution-reference].
- This SHOULD be a fully qualified reference name, without any assumed default registry. (e.g., `registry.example.com/my-org/my-image:tag` instead of `my-org/my-image:tag`).
- This SHOULD be the immediate image sharing zero-indexed layers with the image, such as from a Dockerfile `FROM` statement.
- This SHOULD NOT reference any other images used to generate the contents of the image (e.g., multi-stage Dockerfile builds).
- If the `image.base.name` annotation is specified, the `image.base.digest` annotation SHOULD be the digest of the manifest referenced by the `image.ref.name` annotation.
## Back-compatibility with Label Schema

114
config.md
View File

@ -1,6 +1,6 @@
# OCI Image Configuration
An OCI *Image* is an ordered collection of root filesystem changes and the corresponding execution parameters for use within a container runtime.
An OCI _Image_ is an ordered collection of root filesystem changes and the corresponding execution parameters for use within a container runtime.
This specification outlines the JSON format describing images for use with a container runtime and execution tool and its relationship to filesystem changesets, described in [Layers](layer.md).
This section defines the `application/vnd.oci.image.config.v1+json` [media type](media-types.md).
@ -11,17 +11,17 @@ This specification uses the following terms:
### [Layer](layer.md)
* Image filesystems are composed of *layers*.
* Each layer represents a set of filesystem changes in a tar-based [layer format](layer.md), recording files to be added, changed, or deleted relative to its parent layer.
* Layers do not have configuration metadata such as environment variables or default arguments - these are properties of the image as a whole rather than any particular layer.
* Using a layer-based or union filesystem such as AUFS, or by computing the diff from filesystem snapshots, the filesystem changeset can be used to present a series of image layers as if they were one cohesive filesystem.
- Image filesystems are composed of _layers_.
- Each layer represents a set of filesystem changes in a tar-based [layer format](layer.md), recording files to be added, changed, or deleted relative to its parent layer.
- Layers do not have configuration metadata such as environment variables or default arguments - these are properties of the image as a whole rather than any particular layer.
- Using a layer-based or union filesystem such as AUFS, or by computing the diff from filesystem snapshots, the filesystem changeset can be used to present a series of image layers as if they were one cohesive filesystem.
### Image JSON
* Each image has an associated JSON structure which describes some basic information about the image such as date created, author, as well as execution/runtime configuration like its entrypoint, default arguments, networking, and volumes.
* The JSON structure also references a cryptographic hash of each layer used by the image, and provides history information for those layers.
* This JSON is considered to be immutable, because changing it would change the computed [ImageID](#imageid).
* Changing it means creating a new derived image, instead of changing the existing image.
- Each image has an associated JSON structure which describes some basic information about the image such as date created, author, as well as execution/runtime configuration like its entrypoint, default arguments, networking, and volumes.
- The JSON structure also references a cryptographic hash of each layer used by the image, and provides history information for those layers.
- This JSON is considered to be immutable, because changing it would change the computed [ImageID](#imageid).
- Changing it means creating a new derived image, instead of changing the existing image.
### Layer DiffID
@ -41,7 +41,7 @@ Use in combination with `rootfs.diff_ids` while applying layers to a root filesy
The `ChainID` of an applied set of layers is defined with the following recursion:
```
```text
ChainID(L₀) = DiffID(L₀)
ChainID(L₀|...|Lₙ₋₁|Lₙ) = Digest(ChainID(L₀|...|Lₙ₋₁) + " " + DiffID(Lₙ))
```
@ -63,11 +63,11 @@ If this is true (with some handwaving), `C = x|C` where `x = any application`.
This means that if an attacker can define `x`, relying on `C` provides no guarantee that the layers were applied in any order.
The `ChainID` addresses this problem by being defined as a compound hash.
__We differentiate the changeset `C`, from the order-dependent application `A|B|C` by saying that the resulting rootfs is identified by ChainID(A|B|C), which can be calculated by `ImageConfig.rootfs`.__
**We differentiate the changeset `C`, from the order-dependent application `A|B|C` by saying that the resulting rootfs is identified by ChainID(A|B|C), which can be calculated by `ImageConfig.rootfs`.**
Let's expand the definition of `ChainID(A|B|C)` to explore its internal structure:
```
```text
ChainID(A) = DiffID(A)
ChainID(A|B) = Digest(ChainID(A) + " " + DiffID(B))
ChainID(A|B|C) = Digest(ChainID(A|B) + " " + DiffID(C))
@ -75,7 +75,7 @@ ChainID(A|B|C) = Digest(ChainID(A|B) + " " + DiffID(C))
We can replace each definition and reduce to a single equality:
```
```text
ChainID(A|B|C) = Digest(Digest(DiffID(A) + " " + DiffID(B)) + " " + DiffID(C))
```
@ -92,48 +92,48 @@ Since the [configuration JSON](#image-json) that gets hashed references hashes o
Note: Any OPTIONAL field MAY also be set to null, which is equivalent to being absent.
- **created** *string*, OPTIONAL
- **created** _string_, OPTIONAL
An combined date and time at which the image was created, formatted as defined by [RFC 3339, section 5.6][rfc3339-s5.6].
- **author** *string*, OPTIONAL
- **author** _string_, OPTIONAL
Gives the name and/or email address of the person or entity which created and is responsible for maintaining the image.
- **architecture** *string*, REQUIRED
- **architecture** _string_, REQUIRED
The CPU architecture which the binaries in this image are built to run on.
Configurations SHOULD use, and implementations SHOULD understand, values listed in the Go Language document for [`GOARCH`][go-environment].
- **os** *string*, REQUIRED
- **os** _string_, REQUIRED
The name of the operating system which the image is built to run on.
Configurations SHOULD use, and implementations SHOULD understand, values listed in the Go Language document for [`GOOS`][go-environment].
- **os.version** *string*, OPTIONAL
- **os.version** _string_, OPTIONAL
This OPTIONAL property specifies the version of the operating system targeted by the referenced blob.
Implementations MAY refuse to use manifests where `os.version` is not known to work with the host OS version.
Valid values are implementation-defined. e.g. `10.0.14393.1066` on `windows`.
- **os.features** *array of strings*, OPTIONAL
- **os.features** _array of strings_, OPTIONAL
This OPTIONAL property specifies an array of strings, each specifying a mandatory OS feature.
When `os` is `windows`, image indexes SHOULD use, and implementations SHOULD understand the following values:
- `win32k`: image requires `win32k.sys` on the host (Note: `win32k.sys` is missing on Nano Server)
- **variant** *string*, OPTIONAL
- **variant** _string_, OPTIONAL
The variant of the specified CPU architecture.
Configurations SHOULD use, and implementations SHOULD understand, `variant` values listed in the [Platform Variants](image-index.md#platform-variants) table.
- **config** *object*, OPTIONAL
- **config** _object_, OPTIONAL
The execution parameters which SHOULD be used as a base when running a container using the image.
This field can be `null`, in which case any execution parameters should be specified at creation of the container.
- **User** *string*, OPTIONAL
- **User** _string_, OPTIONAL
The username or UID which is a platform-specific structure that allows specific control over which user the process run as.
This acts as a default value to use when the value is not specified when creating a container.
@ -141,7 +141,7 @@ Note: Any OPTIONAL field MAY also be set to null, which is equivalent to being a
If `group`/`gid` is not specified, the default group and supplementary groups of the given `user`/`uid` in `/etc/passwd` and `/etc/group` from the container are applied.
If `group`/`gid` is specified, supplementary groups from the container are ignored.
- **ExposedPorts** *object*, OPTIONAL
- **ExposedPorts** _object_, OPTIONAL
A set of ports to expose from a container running this image.
Its keys can be in the format of:
@ -149,104 +149,104 @@ Note: Any OPTIONAL field MAY also be set to null, which is equivalent to being a
These values act as defaults and are merged with any specified when creating a container.
**NOTE:** This JSON structure value is unusual because it is a direct JSON serialization of the Go type `map[string]struct{}` and is represented in JSON as an object mapping its keys to an empty object.
- **Env** *array of strings*, OPTIONAL
- **Env** _array of strings_, OPTIONAL
Entries are in the format of `VARNAME=VARVALUE`.
These values act as defaults and are merged with any specified when creating a container.
- **Entrypoint** *array of strings*, OPTIONAL
- **Entrypoint** _array of strings_, OPTIONAL
A list of arguments to use as the command to execute when the container starts.
These values act as defaults and may be replaced by an entrypoint specified when creating a container.
- **Cmd** *array of strings*, OPTIONAL
- **Cmd** _array of strings_, OPTIONAL
Default arguments to the entrypoint of the container.
These values act as defaults and may be replaced by any specified when creating a container.
If an `Entrypoint` value is not specified, then the first entry of the `Cmd` array SHOULD be interpreted as the executable to run.
- **Volumes** *object*, OPTIONAL
- **Volumes** _object_, OPTIONAL
A set of directories describing where the process is likely to write data specific to a container instance.
**NOTE:** This JSON structure value is unusual because it is a direct JSON serialization of the Go type `map[string]struct{}` and is represented in JSON as an object mapping its keys to an empty object.
- **WorkingDir** *string*, OPTIONAL
- **WorkingDir** _string_, OPTIONAL
Sets the current working directory of the entrypoint process in the container.
This value acts as a default and may be replaced by a working directory specified when creating a container.
- **Labels** *object*, OPTIONAL
- **Labels** _object_, OPTIONAL
The field contains arbitrary metadata for the container.
This property MUST use the [annotation rules](annotations.md#rules).
- **StopSignal** *string*, OPTIONAL
- **StopSignal** _string_, OPTIONAL
The field contains the system call signal that will be sent to the container to exit. The signal can be a signal name in the format `SIGNAME`, for instance `SIGKILL` or `SIGRTMIN+3`.
- **ArgsEscaped** *boolean*, OPTIONAL
- **ArgsEscaped** _boolean_, OPTIONAL
`[Deprecated]` - This field is present only for legacy compatibility with Docker and should not be used by new image builders.
It is used by Docker for Windows images to indicate that the `Entrypoint` or `Cmd` or both, contains only a single element array, that is a pre-escaped, and combined into a single string `CommandLine`.
If `true` the value in `Entrypoint` or `Cmd` should be used as-is to avoid double escaping.
Note, the exact behavior of `ArgsEscaped` is complex and subject to implementation details in Moby project.
- **Memory** *integer*, OPTIONAL
- **Memory** _integer_, OPTIONAL
This property is *reserved* for use, to [maintain compatibility](media-types.md#compatibility-matrix).
This property is _reserved_ for use, to [maintain compatibility](media-types.md#compatibility-matrix).
- **MemorySwap** *integer*, OPTIONAL
- **MemorySwap** _integer_, OPTIONAL
This property is *reserved* for use, to [maintain compatibility](media-types.md#compatibility-matrix).
This property is _reserved_ for use, to [maintain compatibility](media-types.md#compatibility-matrix).
- **CpuShares** *integer*, OPTIONAL
- **CpuShares** _integer_, OPTIONAL
This property is *reserved* for use, to [maintain compatibility](media-types.md#compatibility-matrix).
This property is _reserved_ for use, to [maintain compatibility](media-types.md#compatibility-matrix).
- **Healthcheck** *object*, OPTIONAL
- **Healthcheck** _object_, OPTIONAL
This property is *reserved* for use, to [maintain compatibility](media-types.md#compatibility-matrix).
This property is _reserved_ for use, to [maintain compatibility](media-types.md#compatibility-matrix).
- **rootfs** *object*, REQUIRED
- **rootfs** _object_, REQUIRED
The rootfs key references the layer content addresses used by the image.
This makes the image config hash depend on the filesystem hash.
- **type** *string*, REQUIRED
- **type** _string_, REQUIRED
MUST be set to `layers`.
Implementations MUST generate an error if they encounter a unknown value while verifying or unpacking an image.
MUST be set to `layers`.
Implementations MUST generate an error if they encounter a unknown value while verifying or unpacking an image.
- **diff_ids** *array of strings*, REQUIRED
- **diff_ids** _array of strings_, REQUIRED
An array of layer content hashes (`DiffIDs`), in order from first to last.
An array of layer content hashes (`DiffIDs`), in order from first to last.
- **history** *array of objects*, OPTIONAL
- **history** _array of objects_, OPTIONAL
Describes the history of each layer.
The array is ordered from first to last.
The object has the following fields:
- **created** *string*, OPTIONAL
- **created** _string_, OPTIONAL
A combined date and time at which the layer was created, formatted as defined by [RFC 3339, section 5.6][rfc3339-s5.6].
A combined date and time at which the layer was created, formatted as defined by [RFC 3339, section 5.6][rfc3339-s5.6].
- **author** *string*, OPTIONAL
- **author** _string_, OPTIONAL
The author of the build point.
The author of the build point.
- **created_by** *string*, OPTIONAL
- **created_by** _string_, OPTIONAL
The command which created the layer.
The command which created the layer.
- **comment** *string*, OPTIONAL
- **comment** _string_, OPTIONAL
A custom message set when creating the layer.
A custom message set when creating the layer.
- **empty_layer** *boolean*, OPTIONAL
- **empty_layer** _boolean_, OPTIONAL
This field is used to mark if the history item created a filesystem diff.
It is set to true if this history item doesn't correspond to an actual layer in the rootfs section (for example, Dockerfile's [ENV](https://docs.docker.com/engine/reference/builder/#/env) command results in no change to the filesystem).
This field is used to mark if the history item created a filesystem diff.
It is set to true if this history item doesn't correspond to an actual layer in the rootfs section (for example, Dockerfile's [ENV](https://docs.docker.com/engine/reference/builder/#/env) command results in no change to the filesystem).
Any extra fields in the Image JSON struct are considered implementation specific and MUST NOT generate an error by any implementations which are unable to interpret them.

16
considerations.md
View File

@ -1,4 +1,6 @@
# Extensibility
# Considerations
## Extensibility
Implementations storing or copying content MUST NOT modify or alter the content in a way that would change the digest of the content. Examples of these implementations include:
@ -10,7 +12,7 @@ Implementations processing content SHOULD NOT generate an error if they encounte
- A [runtime implementing the runtime specification][runtime-spec]
- An implementation using OCI to retrieve and utilize artifacts, e.g.: a WASM runtime
# Canonicalization
## Canonicalization
- OCI Images are [content-addressable](https://en.wikipedia.org/wiki/Content-addressable_storage). See [descriptors](descriptor.md) for more.
- One benefit of content-addressable storage is easy deduplication.
@ -19,7 +21,7 @@ Implementations processing content SHOULD NOT generate an error if they encounte
- To allow efficient storage, implementations serializing content for blobs SHOULD use a canonical serialization.
- This increases the chance that different implementations can push the same semantic content to the store without creating redundant blobs.
## JSON
### JSON
[JSON][JSON] content SHOULD be serialized as [canonical JSON][canonical-json].
Of the [OCI Image Format Specification media types](media-types.md), all the types ending in `+json` contain JSON content.
@ -27,7 +29,7 @@ Implementations:
- [Go][Go]: [github.com/docker/go][docker-go], which claims to implement [canonical JSON][canonical-json] except for Unicode normalization.
# EBNF
## EBNF
For field formats described in this specification, we use a limited subset of [Extended Backus-Naur Form][ebnf], similar to that used by the [XML specification][xmlebnf].
Grammars present in the OCI specification are regular and can be converted to a single regular expressions.
@ -43,7 +45,7 @@ symbol ::= expression
We can say we have the production identified by symbol if the input is matched by the expression.
Whitespace is completely ignored in rule definitions.
## Expressions
### Expressions
The simplest expression is the literal, surrounded by quotes:
@ -104,7 +106,7 @@ oneof ::= A | B
The above indicates that the expression should match one of the expressions, `A` or `B`.
## Precedence
### Precedence
The operator precedence is in the following order:
@ -118,7 +120,7 @@ The precedence can be better described using grouping to show equivalents.
Concatenation has higher precedence than alternates, such `A B | C D` is equivalent to `(A B) | (C D)`.
Unary operators have higher precedence than alternates and concatenation, such that `A+ | B+` is equivalent to `(A+) | (B+)`.
## Examples
### Examples
The following combines the previous definitions to match a simple, relative path name, describing the individual components:

2
conversion.md
View File

@ -99,7 +99,7 @@ A compliant configuration converter SHOULD provide a way for users to extract th
| `Config.Volumes` | `mounts` | 2 |
1. The runtime configuration does not have a corresponding field for this image field.
However, converters SHOULD set the [`org.opencontainers.image.exposedPorts` annotation](#config.exposedports).
However, converters SHOULD set the [`org.opencontainers.image.exposedPorts` annotation](#configexposedports).
2. Implementations SHOULD provide mounts for these locations such that application data is not written to the container's root filesystem.
If a converter implements conversion for this field using mountpoints, it SHOULD set the `destination` of the mountpoint to the value specified in `Config.Volumes`.
An implementation MAY seed the contents of the mount with data in the image at the same location.

2
descriptor.md
View File

@ -125,7 +125,7 @@ Function `H` returns the hash of `C` in bytes and is passed to function `Encode`
The result `verified` is true if `ID(C)` is equal to `D`, confirming that `C` is the content identified by `D`.
After verification, the following is true:
```
```text
D == ID(C) == '<alg>:' + Encode(H(C))
```

28
image-index.md
View File

@ -7,7 +7,7 @@ This section defines the `application/vnd.oci.image.index.v1+json` [media type](
For the media type(s) that this document is compatible with, see the [matrix][matrix].
## *Image Index* Property Descriptions
## _Image Index_ Property Descriptions
- **`schemaVersion`** *int*
@ -56,33 +56,33 @@ For the media type(s) that this document is compatible with, see the [matrix][ma
- **`architecture`** *string*
This REQUIRED property specifies the CPU architecture.
Image indexes SHOULD use, and implementations SHOULD understand, values listed in the Go Language document for [`GOARCH`][go-environment2].
This REQUIRED property specifies the CPU architecture.
Image indexes SHOULD use, and implementations SHOULD understand, values listed in the Go Language document for [`GOARCH`][go-environment2].
- **`os`** *string*
This REQUIRED property specifies the operating system.
Image indexes SHOULD use, and implementations SHOULD understand, values listed in the Go Language document for [`GOOS`][go-environment2].
This REQUIRED property specifies the operating system.
Image indexes SHOULD use, and implementations SHOULD understand, values listed in the Go Language document for [`GOOS`][go-environment2].
- **`os.version`** *string*
This OPTIONAL property specifies the version of the operating system targeted by the referenced blob.
Implementations MAY refuse to use manifests where `os.version` is not known to work with the host OS version.
Valid values are implementation-defined. e.g. `10.0.14393.1066` on `windows`.
This OPTIONAL property specifies the version of the operating system targeted by the referenced blob.
Implementations MAY refuse to use manifests where `os.version` is not known to work with the host OS version.
Valid values are implementation-defined. e.g. `10.0.14393.1066` on `windows`.
- **`os.features`** *array of strings*
This OPTIONAL property specifies an array of strings, each specifying a mandatory OS feature.
When `os` is `windows`, image indexes SHOULD use, and implementations SHOULD understand the following values:
This OPTIONAL property specifies an array of strings, each specifying a mandatory OS feature.
When `os` is `windows`, image indexes SHOULD use, and implementations SHOULD understand the following values:
- `win32k`: image requires `win32k.sys` on the host (Note: `win32k.sys` is missing on Nano Server)
- `win32k`: image requires `win32k.sys` on the host (Note: `win32k.sys` is missing on Nano Server)
When `os` is not `windows`, values are implementation-defined and SHOULD be submitted to this specification for standardization.
When `os` is not `windows`, values are implementation-defined and SHOULD be submitted to this specification for standardization.
- **`variant`** *string*
This OPTIONAL property specifies the variant of the CPU.
Image indexes SHOULD use, and implementations SHOULD understand, `variant` values listed in the [Platform Variants](#platform-variants) table.
This OPTIONAL property specifies the variant of the CPU.
Image indexes SHOULD use, and implementations SHOULD understand, `variant` values listed in the [Platform Variants](#platform-variants) table.
- **`features`** *array of strings*

70
image-layout.md
View File

@ -1,39 +1,39 @@
## OCI Image Layout Specification
# OCI Image Layout Specification
* The OCI Image Layout is the 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).
* 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).
- The OCI Image Layout is the 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).
- 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).
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/bundle.md) by:
* Following the ref to find a [manifest](manifest.md#image-manifest), possibly via an [image index](image-index.md)
* [Applying the filesystem layers](layer.md#applying) in the specified order
* 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)
- Following the ref to find a [manifest](manifest.md#image-manifest), possibly via an [image index](image-index.md)
- [Applying the filesystem layers](layer.md#applying) in the specified order
- 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)
# Content
## Content
The image layout is as follows:
- `blobs` directory
- Contains content-addressable blobs
- A blob has no schema and SHOULD be considered opaque
- Directory MUST exist and MAY be empty
- See [blobs](#blobs) section
- Contains content-addressable blobs
- A blob has no schema and SHOULD be considered opaque
- Directory MUST exist and MAY be empty
- See [blobs](#blobs) section
- `oci-layout` file
- It MUST exist
- It MUST be a JSON object
- It MUST contain an `imageLayoutVersion` field
- See [oci-layout file](#oci-layout-file) section
- It MAY include additional fields
- It MUST exist
- It MUST be a JSON object
- It MUST contain an `imageLayoutVersion` field
- See [oci-layout file](#oci-layout-file) section
- It MAY include additional fields
- `index.json` file
- It MUST exist
- It MUST be an [image index](image-index.md) JSON object.
- See [index.json](#indexjson-file) section
- It MUST exist
- It MUST be an [image index](image-index.md) JSON object.
- See [index.json](#indexjson-file) section
## Example Layout
This is an example image layout:
```
```shell
$ cd example.com/app/
$ find . -type f
./index.json
@ -45,22 +45,22 @@ $ find . -type f
Blobs are named by their contents:
```
```shell
$ shasum -a 256 ./blobs/sha256/afff3924849e458c5ef237db5f89539274d5e609db5db935ed3959c90f1f2d51
afff3924849e458c5ef237db5f89539274d5e609db5db935ed3959c90f1f2d51 ./blobs/sha256/afff3924849e458c5ef237db5f89539274d5e609db5db935ed3959c90f1f2d51
```
## Blobs
* Object names in the `blobs` subdirectories are composed of a directory for each hash algorithm, the children of which will contain the actual content.
* 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`.
* The character set of the entry name for `<alg>` and `<encoded>` MUST match the respective grammar elements described in [descriptor](descriptor.md#digests).
* The blobs directory MAY contain blobs which are not referenced by any of the [refs](#indexjson-file).
* The blobs directory MAY be missing referenced blobs, in which case the missing blobs SHOULD be fulfilled by an external blob store.
- Object names in the `blobs` subdirectories are composed of a directory for each hash algorithm, the children of which will contain the actual content.
- 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`.
- The character set of the entry name for `<alg>` and `<encoded>` MUST match the respective grammar elements described in [descriptor](descriptor.md#digests).
- The blobs directory MAY contain blobs which are not referenced by any of the [refs](#indexjson-file).
- The blobs directory MAY be missing referenced blobs, in which case the missing blobs SHOULD be fulfilled by an external blob store.
### Example Blobs
```
```shell
$ cat ./blobs/sha256/9b97579de92b1c195b85bb42a11011378ee549b02d7fe9c17bf2a6b35d5cb079 | jq
{
"schemaVersion": 2,
@ -77,7 +77,7 @@ $ cat ./blobs/sha256/9b97579de92b1c195b85bb42a11011378ee549b02d7fe9c17bf2a6b35d5
...
```
```
```shell
$ cat ./blobs/sha256/afff3924849e458c5ef237db5f89539274d5e609db5db935ed3959c90f1f2d51 | jq
{
"schemaVersion": 2,
@ -95,7 +95,7 @@ $ cat ./blobs/sha256/afff3924849e458c5ef237db5f89539274d5e609db5db935ed3959c90f1
...
```
```
```shell
$ cat ./blobs/sha256/5b0bcabd1ed22e9fb1310cf6c2dec7cdef19f0ad69efa1f392e94a4333501270 | jq
{
"architecture": "amd64",
@ -118,7 +118,7 @@ $ cat ./blobs/sha256/5b0bcabd1ed22e9fb1310cf6c2dec7cdef19f0ad69efa1f392e94a43335
...
```
```
```shell
$ cat ./blobs/sha256/9834876dcfb05cb167a5c24953eba58c4ac89b1adf57f28f2f9d09af107ee8f0
[gzipped tar stream]
```
@ -144,11 +144,10 @@ The [image index](image-index.md) is a multi-descriptor entry point.
This index provides an established path (`/index.json`) to have an entry point for an image-layout and to discover auxiliary descriptors.
* No semantic restriction is given for the "org.opencontainers.image.ref.name" annotation of descriptors.
* 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`.
* Future versions of the spec MAY use a different mediatype (i.e. a new versioned format).
* An encountered `mediaType` that is unknown MUST NOT generate an error.
- No semantic restriction is given for the "org.opencontainers.image.ref.name" annotation of descriptors.
- 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`.
- Future versions of the spec MAY use a different mediatype (i.e. a new versioned format).
- An encountered `mediaType` that is unknown MUST NOT generate an error.
**Implementor's Note:**
A common use case of descriptors with a "org.opencontainers.image.ref.name" annotation is representing a "tag" for a container image.
@ -156,7 +155,6 @@ For example, an image may have a tag for different versions or builds of the sof
In the wild you often see "tags" like "v1.0.0-vendor.0", "2.0.0-debug", etc.
Those 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.
### Index Example
```json,title=Image%20Index&mediatype=application/vnd.oci.image.index.v1%2Bjson

28
implementations.md
View File

@ -2,25 +2,25 @@
Projects or Companies currently adopting the OCI Image Specification
* [projectatomic/skopeo](https://github.com/projectatomic/skopeo)
* [Amazon Elastic Container Registry (ECR)](https://docs.aws.amazon.com/AmazonECR/latest/userguide/image-manifest-formats.html) ([announcement](https://aws.amazon.com/about-aws/whats-new/2017/01/amazon-ecr-supports-docker-image-manifest-v2-schema-2/))
* [Azure Container Registry (ACR)](https://docs.microsoft.com/azure/container-registry/container-registry-image-formats#oci-images)
* [openSUSE/umoci](https://github.com/openSUSE/umoci)
* [cloudfoundry/grootfs](https://github.com/cloudfoundry/grootfs) ([source](https://github.com/cloudfoundry/grootfs/blob/c3da26e1e463b51be1add289032f3dca6698b335/fetcher/remote/docker_src.go))
* [Mesos plans](https://issues.apache.org/jira/browse/MESOS-5011) ([design doc](https://docs.google.com/document/d/1Pus7D-inIBoLSIPyu3rl_apxvUhtp3rp0_b0Ttr2Xww/edit#heading=h.hrvk2wboog4p))
* [Docker](https://github.com/docker)
- [projectatomic/skopeo](https://github.com/projectatomic/skopeo)
- [Amazon Elastic Container Registry (ECR)](https://docs.aws.amazon.com/AmazonECR/latest/userguide/image-manifest-formats.html) ([announcement](https://aws.amazon.com/about-aws/whats-new/2017/01/amazon-ecr-supports-docker-image-manifest-v2-schema-2/))
- [Azure Container Registry (ACR)](https://docs.microsoft.com/azure/container-registry/container-registry-image-formats#oci-images)
- [openSUSE/umoci](https://github.com/openSUSE/umoci)
- [cloudfoundry/grootfs](https://github.com/cloudfoundry/grootfs) ([source](https://github.com/cloudfoundry/grootfs/blob/c3da26e1e463b51be1add289032f3dca6698b335/fetcher/remote/docker_src.go))
- [Mesos plans](https://issues.apache.org/jira/browse/MESOS-5011) ([design doc](https://docs.google.com/document/d/1Pus7D-inIBoLSIPyu3rl_apxvUhtp3rp0_b0Ttr2Xww/edit#heading=h.hrvk2wboog4p))
- [Docker](https://github.com/docker)
- [docker/docker (`docker save/load` WIP)](https://github.com/docker/docker/pull/26369)
- [distribution/distribution (registry PR)](https://github.com/distribution/distribution/pull/2076)
* [containerd/containerd](https://github.com/containerd/containerd)
* [Containers](https://github.com/containers/)
- [containerd/containerd](https://github.com/containerd/containerd)
- [Containers](https://github.com/containers/)
- [containers/build](https://github.com/containers/build)
- [containers/image](https://github.com/containers/image)
- [containers/oci-spec-rs](https://github.com/containers/oci-spec-rs)
- [containers/libocispec](https://github.com/containers/libocispec)
* [krustlet/oci-distribution](https://github.com/krustlet/oci-distribution)
* [coreos/rkt](https://github.com/coreos/rkt)
* [box-builder/box](https://github.com/box-builder/box)
* [coolljt0725/docker2oci](https://github.com/coolljt0725/docker2oci)
* [regclient/regclient](https://github.com/regclient/regclient)
- [krustlet/oci-distribution](https://github.com/krustlet/oci-distribution)
- [coreos/rkt](https://github.com/coreos/rkt)
- [box-builder/box](https://github.com/box-builder/box)
- [coolljt0725/docker2oci](https://github.com/coolljt0725/docker2oci)
- [regclient/regclient](https://github.com/regclient/regclient)
_(to add your project please open a [pull-request](https://github.com/opencontainers/image-spec/pulls))_

186
layer.md
View File

@ -8,26 +8,26 @@ This section defines the `application/vnd.oci.image.layer.v1.tar`, `application/
## `+gzip` Media Types
* The media type `application/vnd.oci.image.layer.v1.tar+gzip` represents an `application/vnd.oci.image.layer.v1.tar` payload which has been compressed with [gzip][rfc1952_2].
* The media type `application/vnd.oci.image.layer.nondistributable.v1.tar+gzip` represents an `application/vnd.oci.image.layer.nondistributable.v1.tar` payload which has been compressed with [gzip][rfc1952_2].
- The media type `application/vnd.oci.image.layer.v1.tar+gzip` represents an `application/vnd.oci.image.layer.v1.tar` payload which has been compressed with [gzip][rfc1952_2].
- The media type `application/vnd.oci.image.layer.nondistributable.v1.tar+gzip` represents an `application/vnd.oci.image.layer.nondistributable.v1.tar` payload which has been compressed with [gzip][rfc1952_2].
## `+zstd` Media Types
* The media type `application/vnd.oci.image.layer.v1.tar+zstd` represents an `application/vnd.oci.image.layer.v1.tar` payload which has been compressed with [zstd][rfc8478].
* The media type `application/vnd.oci.image.layer.nondistributable.v1.tar+zstd` represents an `application/vnd.oci.image.layer.nondistributable.v1.tar` payload which has been compressed with [zstd][rfc8478].
- The media type `application/vnd.oci.image.layer.v1.tar+zstd` represents an `application/vnd.oci.image.layer.v1.tar` payload which has been compressed with [zstd][rfc8478].
- The media type `application/vnd.oci.image.layer.nondistributable.v1.tar+zstd` represents an `application/vnd.oci.image.layer.nondistributable.v1.tar` payload which has been compressed with [zstd][rfc8478].
## Distributable Format
* Layer Changesets for the [media type](media-types.md) `application/vnd.oci.image.layer.v1.tar` MUST be packaged in [tar archive][tar-archive].
* Layer Changesets for the [media type](media-types.md) `application/vnd.oci.image.layer.v1.tar` MUST NOT include duplicate entries for file paths in the resulting [tar archive][tar-archive].
- Layer Changesets for the [media type](media-types.md) `application/vnd.oci.image.layer.v1.tar` MUST be packaged in [tar archive][tar-archive].
- Layer Changesets for the [media type](media-types.md) `application/vnd.oci.image.layer.v1.tar` MUST NOT include duplicate entries for file paths in the resulting [tar archive][tar-archive].
## Change Types
Types of changes that can occur in a changeset are:
* Additions
* Modifications
* Removals
- Additions
- Modifications
- Removals
Additions and Modifications are represented the same in the changeset tar archive.
@ -37,42 +37,42 @@ Removals are represented using "[whiteout](#whiteouts)" file entries (See [Repre
Throughout this document section, the use of word "files" or "entries" includes the following, where supported:
* regular files
* directories
* sockets
* symbolic links
* block devices
* character devices
* FIFOs
- regular files
- directories
- sockets
- symbolic links
- block devices
- character devices
- FIFOs
### File Attributes
Where supported, MUST include file attributes for Additions and Modifications include:
* Modification Time (`mtime`)
* User ID (`uid`)
* User Name (`uname`) *secondary to `uid`*
* Group ID (`gid `)
* Group Name (`gname`) *secondary to `gid`*
* Mode (`mode`)
* Extended Attributes (`xattrs`)
* Symlink reference (`linkname` + symbolic link type)
* [Hardlink](#hardlinks) reference (`linkname`)
- Modification Time (`mtime`)
- User ID (`uid`)
- User Name (`uname`) *secondary to `uid`*
- Group ID (`gid`)
- Group Name (`gname`) *secondary to `gid`*
- Mode (`mode`)
- Extended Attributes (`xattrs`)
- Symlink reference (`linkname` + symbolic link type)
- [Hardlink](#hardlinks) reference (`linkname`)
[Sparse files](https://en.wikipedia.org/wiki/Sparse_file) SHOULD NOT be used because they lack consistent support across tar implementations.
#### Hardlinks
* Hardlinks are a [POSIX concept](https://pubs.opengroup.org/onlinepubs/9699919799/functions/link.html) for having one or more directory entries for the same file on the same device.
* Not all filesystems support hardlinks (e.g. [FAT](https://en.wikipedia.org/wiki/File_Allocation_Table)).
* Hardlinks are possible with all [file types](#file-types) except `directories`.
* Non-directory files are considered "hardlinked" when their link count is greater than 1.
* Hardlinked files are on a same device (i.e. comparing Major:Minor pair) and have the same inode.
* The corresponding files that share the link with the > 1 linkcount may be outside the directory that the changeset is being produced from, in which case the `linkname` is not recorded in the changeset.
* Hardlinks are stored in a tar archive with type of a `1` char, per the [GNU Basic Tar Format][gnu-tar-standard] and [libarchive tar(5)][libarchive-tar].
* While approaches to deriving new or changed hardlinks may vary, a possible approach is:
- Hardlinks are a [POSIX concept](https://pubs.opengroup.org/onlinepubs/9699919799/functions/link.html) for having one or more directory entries for the same file on the same device.
- Not all filesystems support hardlinks (e.g. [FAT](https://en.wikipedia.org/wiki/File_Allocation_Table)).
- Hardlinks are possible with all [file types](#file-types) except `directories`.
- Non-directory files are considered "hardlinked" when their link count is greater than 1.
- Hardlinked files are on a same device (i.e. comparing Major:Minor pair) and have the same inode.
- The corresponding files that share the link with the > 1 linkcount may be outside the directory that the changeset is being produced from, in which case the `linkname` is not recorded in the changeset.
- Hardlinks are stored in a tar archive with type of a `1` char, per the [GNU Basic Tar Format][gnu-tar-standard] and [libarchive tar(5)][libarchive-tar].
- While approaches to deriving new or changed hardlinks may vary, a possible approach is:
```
```text
SET LinkMap to map[< Major:Minor String >]map[< inode integer >]< path string >
SET LinkNames to map[< src path string >]< dest path string >
FOR each path in root path
@ -98,10 +98,10 @@ With this approach, the link map and links names of a directory could be compare
Implementations on Windows MUST support these additional attributes, encoded in [PAX vendor
extensions](https://github.com/libarchive/libarchive/wiki/ManPageTar5#pax-interchange-format) as follows:
* [Windows file attributes](https://msdn.microsoft.com/en-us/library/windows/desktop/gg258117(v=vs.85).aspx) (`MSWINDOWS.fileattr`)
* [Security descriptor](https://msdn.microsoft.com/en-us/library/cc230366.aspx) (`MSWINDOWS.rawsd`): base64-encoded self-relative binary security descriptor
* Mount points (`MSWINDOWS.mountpoint`): if present on a directory symbolic link, then the link should be created as a [directory junction](https://en.wikipedia.org/wiki/NTFS_junction_point)
* Creation time (`LIBARCHIVE.creationtime`)
- [Windows file attributes](https://msdn.microsoft.com/en-us/library/windows/desktop/gg258117(v=vs.85).aspx) (`MSWINDOWS.fileattr`)
- [Security descriptor](https://msdn.microsoft.com/en-us/library/cc230366.aspx) (`MSWINDOWS.rawsd`): base64-encoded self-relative binary security descriptor
- Mount points (`MSWINDOWS.mountpoint`): if present on a directory symbolic link, then the link should be created as a [directory junction](https://en.wikipedia.org/wiki/NTFS_junction_point)
- Creation time (`LIBARCHIVE.creationtime`)
## Creating
@ -114,7 +114,7 @@ The name of the directory is not relevant to the layer itself, only for the purp
Here is an initial empty directory structure for a changeset, with a unique directory name `rootfs-c9d-v1`.
```
```text
rootfs-c9d-v1/
```
@ -122,19 +122,19 @@ rootfs-c9d-v1/
Files and directories are then created:
```
```text
rootfs-c9d-v1/
etc/
my-app-config
bin/
my-app-binary
my-app-tools
etc/
my-app-config
bin/
my-app-binary
my-app-tools
```
The `rootfs-c9d-v1` directory is then created as a plain [tar archive][tar-archive] with relative path to `rootfs-c9d-v1`.
Entries for the following files:
```
```text
./
./etc/
./etc/my-app-config
@ -147,9 +147,10 @@ Entries for the following files:
Create a new directory and initialize it with a copy or snapshot of the prior root filesystem.
Example commands that can preserve [file attributes](#file-attributes) to make this copy are:
* [cp(1)](https://linux.die.net/man/1/cp): `cp -a rootfs-c9d-v1/ rootfs-c9d-v1.s1/`
* [rsync(1)](https://linux.die.net/man/1/rsync): `rsync -aHAX rootfs-c9d-v1/ rootfs-c9d-v1.s1/`
* [tar(1)](https://linux.die.net/man/1/tar): `mkdir rootfs-c9d-v1.s1 && tar --acls --xattrs -C rootfs-c9d-v1/ -c . | tar -C rootfs-c9d-v1.s1/ --acls --xattrs -x` (including `--selinux` where supported)
- [cp(1)](https://linux.die.net/man/1/cp): `cp -a rootfs-c9d-v1/ rootfs-c9d-v1.s1/`
- [rsync(1)](https://linux.die.net/man/1/rsync): `rsync -aHAX rootfs-c9d-v1/ rootfs-c9d-v1.s1/`
- [tar(1)](https://linux.die.net/man/1/tar): `mkdir rootfs-c9d-v1.s1 && tar --acls --xattrs -C rootfs-c9d-v1/ -c . | tar -C rootfs-c9d-v1.s1/ --acls --xattrs -x` (including `--selinux` where supported)
Any [changes](#change-types) to the snapshot MUST NOT change or affect the directory it was copied from.
@ -160,13 +161,13 @@ In this way `rootfs-c9d-v1.s1` is prepared for updates and alterations.
Initial layout of the snapshot:
```
```text
rootfs-c9d-v1.s1/
etc/
my-app-config
bin/
my-app-binary
my-app-tools
etc/
my-app-config
bin/
my-app-binary
my-app-tools
```
See [Change Types](#change-types) for more details on changes.
@ -176,14 +177,14 @@ Also a change (in attribute or file content) to `./bin/my-app-tools` binary to h
Following these changes, the representation of the `rootfs-c9d-v1.s1` directory:
```
```text
rootfs-c9d-v1.s1/
etc/
my-app.d/
default.cfg
bin/
my-app-binary
my-app-tools
etc/
my-app.d/
default.cfg
bin/
my-app-binary
my-app-tools
```
### Determining Changes
@ -195,7 +196,7 @@ For this example, `rootfs-c9d-v1/` and `rootfs-c9d-v1.s1/` are recursively compa
The following changeset is found:
```
```text
Added: /etc/my-app.d/
Added: /etc/my-app.d/default.cfg
Modified: /bin/my-app-tools
@ -207,14 +208,14 @@ This reflects the removal of `/etc/my-app-config` and creation of a file and dir
### Representing Changes
A [tar archive][tar-archive] is then created which contains *only* this changeset:
A [tar archive][tar-archive] is then created which contains _only_ this changeset:
- Added and modified files and directories in their entirety
- Deleted files or directories marked with a [whiteout file](#whiteouts)
The resulting tar archive for `rootfs-c9d-v1.s1` has the following entries:
```
```text
./etc/my-app.d/
./etc/my-app.d/default.cfg
./bin/my-app-tools
@ -225,9 +226,9 @@ To signify that the resource `./etc/my-app-config` MUST be removed when the chan
## Applying Changesets
* Layer Changesets of [media type](media-types.md) `application/vnd.oci.image.layer.v1.tar` are _applied_, rather than simply extracted as tar archives.
* Applying a layer changeset requires special consideration for the [whiteout](#whiteouts) files.
* In the absence of any [whiteout](#whiteouts) files in a layer changeset, the archive is extracted like a regular tar archive.
- Layer Changesets of [media type](media-types.md) `application/vnd.oci.image.layer.v1.tar` are _applied_, rather than simply extracted as tar archives.
- Applying a layer changeset requires special consideration for the [whiteout](#whiteouts) files.
- In the absence of any [whiteout](#whiteouts) files in a layer changeset, the archive is extracted like a regular tar archive.
### Changeset over existing files
@ -235,21 +236,22 @@ This section specifies applying an entry from a layer changeset if the target pa
If the entry and the existing path are both directories, then the existing path's attributes MUST be replaced by those of the entry in the changeset.
In all other cases, the implementation MUST do the semantic equivalent of the following:
- removing the file path (e.g. [`unlink(2)`](https://linux.die.net/man/2/unlink) on Linux systems)
- recreating the file path, based on the contents and attributes of the changeset entry
## Whiteouts
* A whiteout file is an empty file with a special filename that signifies a path should be deleted.
* A whiteout filename consists of the prefix `.wh.` plus the basename of the path to be deleted.
* As files prefixed with `.wh.` are special whiteout markers, it is not possible to create a filesystem which has a file or directory with a name beginning with `.wh.`.
* Once a whiteout is applied, the whiteout itself MUST also be hidden.
* Whiteout files MUST only apply to resources in lower/parent layers.
* Files that are present in the same layer as a whiteout file can only be hidden by whiteout files in subsequent layers.
- A whiteout file is an empty file with a special filename that signifies a path should be deleted.
- A whiteout filename consists of the prefix `.wh.` plus the basename of the path to be deleted.
- As files prefixed with `.wh.` are special whiteout markers, it is not possible to create a filesystem which has a file or directory with a name beginning with `.wh.`.
- Once a whiteout is applied, the whiteout itself MUST also be hidden.
- Whiteout files MUST only apply to resources in lower/parent layers.
- Files that are present in the same layer as a whiteout file can only be hidden by whiteout files in subsequent layers.
The following is a base layer with several resources:
```
```text
a/
a/b/
a/b/c/
@ -258,7 +260,7 @@ a/b/c/bar
When the next layer is created, the original `a/b` directory is deleted and recreated with `a/b/c/foo`:
```
```text
a/
a/.wh..wh..opq
a/b/
@ -269,7 +271,7 @@ a/b/c/foo
When processing the second layer, `a/.wh..wh..opq` is applied first, before creating the new version of `a/b`, regardless of the ordering in which the whiteout file was encountered.
For example, the following layer is equivalent to the layer above:
```
```text
a/
a/b/
a/b/c/
@ -281,37 +283,37 @@ Implementations SHOULD generate layers such that the whiteout files appear befor
### Opaque Whiteout
* In addition to expressing that a single entry should be removed from a lower layer, layers may remove all of the children using an opaque whiteout entry.
* An opaque whiteout entry is a file with the name `.wh..wh..opq` indicating that all siblings are hidden in the lower layer.
- In addition to expressing that a single entry should be removed from a lower layer, layers may remove all of the children using an opaque whiteout entry.
- An opaque whiteout entry is a file with the name `.wh..wh..opq` indicating that all siblings are hidden in the lower layer.
Let's take the following base layer as an example:
```
```text
etc/
my-app-config
my-app-config
bin/
my-app-binary
my-app-tools
tools/
my-app-tool-one
my-app-binary
my-app-tools
tools/
my-app-tool-one
```
If all children of `bin/` are removed, the next layer would have the following:
```
```text
bin/
.wh..wh..opq
.wh..wh..opq
```
This is called _opaque whiteout_ format.
An _opaque whiteout_ file hides _all_ children of the `bin/` including sub-directories and all descendants.
Using _explicit whiteout_ files, this would be equivalent to the following:
```
```text
bin/
.wh.my-app-binary
.wh.my-app-tools
.wh.tools
.wh.my-app-binary
.wh.my-app-tools
.wh.tools
```
In this case, a unique whiteout file is generated for each entry.
@ -322,7 +324,7 @@ Implementations SHOULD generate layers using _explicit whiteout_ files, but MUST
Any given image is likely to be composed of several of these Image Filesystem Changeset tar archives.
# Non-Distributable Layers
## Non-Distributable Layers
> **NOTE**: Non-distributable layers are deprecated, and not recommended for future use.
> Implementations SHOULD NOT produce new non-distributable layers.

81
manifest.md
View File

@ -9,11 +9,11 @@ The third goal is to be [translatable](conversion.md) to the [OCI Runtime Specif
This section defines the `application/vnd.oci.image.manifest.v1+json` [media type](media-types.md).
For the media type(s) that this is compatible with see the [matrix](media-types.md#compatibility-matrix).
# Image Manifest
## Image Manifest
Unlike the [image index](image-index.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.
## *Image Manifest* Property Descriptions
## _Image Manifest_ Property Descriptions
- **`schemaVersion`** *int*
@ -35,77 +35,78 @@ Unlike the [image index](image-index.md), which contains information about a set
- **`config`** *[descriptor](descriptor.md)*
This REQUIRED property references a configuration object for a container, by digest.
Beyond the [descriptor requirements](descriptor.md#properties), the value has the following additional restrictions:
This REQUIRED property references a configuration object for a container, by digest.
Beyond the [descriptor requirements](descriptor.md#properties), the value has the following additional restrictions:
- **`mediaType`** *string*
- **`mediaType`** *string*
This [descriptor property](descriptor.md#properties) has additional restrictions for `config`.
This [descriptor property](descriptor.md#properties) has additional restrictions for `config`.
Implementations MUST NOT attempt to parse the referenced content if this media type is unknown and instead consider the referenced content as arbitrary binary data (e.g.: as `application/octet-stream`).
Implementations MUST NOT attempt to parse the referenced content if this media type is unknown and instead consider the referenced content as arbitrary binary data (e.g.: as `application/octet-stream`).
Implementations storing or copying image manifests MUST NOT error on encountering a value that is unknown to the implementation.
Implementations storing or copying image manifests MUST NOT error on encountering a value that is unknown to the implementation.
Implementations MUST support at least the following media types:
Implementations MUST support at least the following media types:
- [`application/vnd.oci.image.config.v1+json`](config.md)
- [`application/vnd.oci.image.config.v1+json`](config.md)
Manifests for container images concerned with portability SHOULD use one of the above media types.
Manifests for artifacts concerned with portability SHOULD use `config.mediaType` as described in [Guidelines for Artifact Usage](#guidelines-for-artifact-usage).
Manifests for container images concerned with portability SHOULD use one of the above media types.
Manifests for artifacts concerned with portability SHOULD use `config.mediaType` as described in [Guidelines for Artifact Usage](#guidelines-for-artifact-usage).
If the manifest uses a different media type than the above, it MUST comply with [RFC 6838][rfc6838], including the [naming requirements in its section 4.2][rfc6838-s4.2], and MAY be registered with [IANA][iana].
If the manifest uses a different media type than the above, it MUST comply with [RFC 6838][rfc6838], including the [naming requirements in its section 4.2][rfc6838-s4.2], and MAY be registered with [IANA][iana].
To set an effectively null or empty config and maintain portability see the [guidance for an empty descriptor](#guidance-for-an-empty-descriptor) below, and `DescriptorEmptyJSON` of the reference code.
To set an effectively null or empty config and maintain portability see the [guidance for an empty descriptor](#guidance-for-an-empty-descriptor) below, and `DescriptorEmptyJSON` of the reference code.
- **`layers`** *array of objects*
Each item in the array MUST be a [descriptor](descriptor.md).
For portability, `layers` SHOULD have at least one entry.
See the [guidance for an empty descriptor](#guidance-for-an-empty-descriptor) below, and `DescriptorEmptyJSON` of the reference code.
Each item in the array MUST be a [descriptor](descriptor.md).
For portability, `layers` SHOULD have at least one entry.
See the [guidance for an empty descriptor](#guidance-for-an-empty-descriptor) below, and `DescriptorEmptyJSON` of the reference code.
When the `config.mediaType` is set to `application/vnd.oci.image.config.v1+json`, the following additional restrictions apply:
When the `config.mediaType` is set to `application/vnd.oci.image.config.v1+json`, the following additional restrictions apply:
- The array MUST have the base layer at index 0.
- Subsequent layers MUST then follow in stack order (i.e. from `layers[0]` to `layers[len(layers)-1]`).
- The final filesystem layout MUST match the result of [applying](layer.md#applying-changesets) the layers to an empty directory.
- The [ownership, mode, and other attributes](layer.md#file-attributes) of the initial empty directory are unspecified.
- The array MUST have the base layer at index 0.
- Subsequent layers MUST then follow in stack order (i.e. from `layers[0]` to `layers[len(layers)-1]`).
- The final filesystem layout MUST match the result of [applying](layer.md#applying-changesets) the layers to an empty directory.
- The [ownership, mode, and other attributes](layer.md#file-attributes) of the initial empty directory are unspecified.
Beyond the [descriptor requirements](descriptor.md#properties), the value has the following additional restrictions:
Beyond the [descriptor requirements](descriptor.md#properties), the value has the following additional restrictions:
- **`mediaType`** *string*
- **`mediaType`** *string*
This [descriptor property](descriptor.md#properties) has additional restrictions for `layers[]`.
Implementations MUST support at least the following media types:
This [descriptor property](descriptor.md#properties) has additional restrictions for `layers[]`.
Implementations MUST support at least the following media types:
- [`application/vnd.oci.image.layer.v1.tar`](layer.md)
- [`application/vnd.oci.image.layer.v1.tar+gzip`](layer.md#gzip-media-types)
- [`application/vnd.oci.image.layer.nondistributable.v1.tar`](layer.md#non-distributable-layers)
- [`application/vnd.oci.image.layer.nondistributable.v1.tar+gzip`](layer.md#gzip-media-types)
- [`application/vnd.oci.image.layer.v1.tar`](layer.md)
- [`application/vnd.oci.image.layer.v1.tar+gzip`](layer.md#gzip-media-types)
- [`application/vnd.oci.image.layer.nondistributable.v1.tar`](layer.md#non-distributable-layers)
- [`application/vnd.oci.image.layer.nondistributable.v1.tar+gzip`](layer.md#gzip-media-types)
Manifests concerned with portability SHOULD use one of the above media types.
Implementations storing or copying image manifests MUST NOT error on encountering a `mediaType` that is unknown to the implementation.
Manifests concerned with portability SHOULD use one of the above media types.
Implementations storing or copying image manifests MUST NOT error on encountering a `mediaType` that is unknown to the implementation.
Entries in this field will frequently use the `+gzip` types.
Entries in this field will frequently use the `+gzip` types.
If the manifest uses a different media type than the above, it MUST comply with [RFC 6838][rfc6838], including the [naming requirements in its section 4.2][rfc6838-s4.2], and MAY be registered with [IANA][iana].
If the manifest uses a different media type than the above, it MUST comply with [RFC 6838][rfc6838], including the [naming requirements in its section 4.2][rfc6838-s4.2], and MAY be registered with [IANA][iana].
See [Guidelines for Artifact Usage](#guidelines-for-artifact-usage) for other uses of the `layers`.
See [Guidelines for Artifact Usage](#guidelines-for-artifact-usage) for other uses of the `layers`.
- **`subject`** *[descriptor](descriptor.md)*
This OPTIONAL property specifies a [descriptor](descriptor.md) of another manifest.
This value, used by the [`referrers` API](https://github.com/opencontainers/distribution-spec/blob/main/spec.md#listing-referrers), indicates a relationship to the specified manifest.
This OPTIONAL property specifies a [descriptor](descriptor.md) of another manifest.
This value, used by the [`referrers` API](https://github.com/opencontainers/distribution-spec/blob/main/spec.md#listing-referrers), indicates a relationship to the specified manifest.
- **`annotations`** *string-string map*
This OPTIONAL property contains arbitrary metadata for the image manifest.
This OPTIONAL property MUST use the [annotation rules](annotations.md#rules).
This OPTIONAL property contains arbitrary metadata for the image manifest.
This OPTIONAL property MUST use the [annotation rules](annotations.md#rules).
See [Pre-Defined Annotation Keys](annotations.md#pre-defined-annotation-keys).
See [Pre-Defined Annotation Keys](annotations.md#pre-defined-annotation-keys).
## Example Image Manifest
*Example showing an image manifest:*
```json,title=Manifest&mediatype=application/vnd.oci.image.manifest.v1%2Bjson
{
"schemaVersion": 2,

24
media-types.md
View File

@ -24,13 +24,13 @@ The following media types identify a ["Layer" with distribution restrictions](la
For example, a HTTP response might return a manifest with the Content-Type header set to `application/vnd.oci.image.manifest.v1+json`.
Implementations MAY also have expectations for the blob's media type and digest (e.g. from a [descriptor](descriptor.md) referencing the blob).
* Implementations that do not have an expected media type for the blob SHOULD respect the returned media type.
* Implementations that have an expected media type which matches the returned media type SHOULD respect the matched media type.
* Implementations that have an expected media type which does not match the returned media type SHOULD:
* Respect the expected media type if the blob matches the expected digest.
Implementations MAY warn about the media type mismatch.
* Return an error if the blob does not match the expected digest (as [recommended for descriptors](descriptor.md#properties)).
* Return an error if they do not have an expected digest.
- Implementations that do not have an expected media type for the blob SHOULD respect the returned media type.
- Implementations that have an expected media type which matches the returned media type SHOULD respect the matched media type.
- Implementations that have an expected media type which does not match the returned media type SHOULD:
- Respect the expected media type if the blob matches the expected digest.
Implementations MAY warn about the media type mismatch.
- Return an error if the blob does not match the expected digest (as [recommended for descriptors](descriptor.md#properties)).
- Return an error if they do not have an expected digest.
## Compatibility Matrix
@ -40,7 +40,7 @@ This section shows where the OCI Image Specification is compatible with formats
### application/vnd.oci.image.index.v1+json
**Similar/related schema**
Similar/related schema:
- [application/vnd.docker.distribution.manifest.list.v2+json](https://github.com/distribution/distribution/blob/master/docs/spec/manifest-v2-2.md#manifest-list)
- `.annotations`: only present in OCI
@ -49,7 +49,7 @@ This section shows where the OCI Image Specification is compatible with formats
### application/vnd.oci.image.manifest.v1+json
**Similar/related schema**
Similar/related schema:
- [application/vnd.docker.distribution.manifest.v2+json](https://github.com/distribution/distribution/blob/master/docs/spec/manifest-v2-2.md#image-manifest-field-descriptions)
- `.annotations`: only present in OCI
@ -59,13 +59,13 @@ This section shows where the OCI Image Specification is compatible with formats
### application/vnd.oci.image.layer.v1.tar+gzip
**Interchangeable and fully compatible mime-types**
Interchangeable and fully compatible mime-types:
- [application/vnd.docker.image.rootfs.diff.tar.gzip](https://github.com/moby/moby/blob/v20.10.8/image/spec/v1.2.md#creating-an-image-filesystem-changeset)
### application/vnd.oci.image.config.v1+json
**Similar/related schema**
Similar/related schema:
- [application/vnd.docker.container.image.v1+json](https://github.com/moby/moby/blob/v20.10.8/image/spec/v1.2.md#image-json-description) (Docker Image Spec v1.2)
- `.config.Memory`: only present in Docker, and reserved in OCI
@ -81,7 +81,7 @@ This section shows where the OCI Image Specification is compatible with formats
The following figure shows how the above media types reference each other:
![](img/media-types.png)
![media types](img/media-types.png)
[Descriptors](descriptor.md) are used for all references.
The image-index being a "fat manifest" references a list of image manifests per target platform. An image manifest references exactly one target configuration and possibly many layers.

5
project.md
View File

@ -2,6 +2,5 @@
## Release Process
* `git tag` the prior commit (preferably signed tag)
* Make a release on [github.com/opencontainers/image-spec](https://github.com/opencontainers/image-spec/releases) for the version. Attach the produced docs.
- `git tag` the prior commit (preferably signed tag)
- Make a release on [github.com/opencontainers/image-spec](https://github.com/opencontainers/image-spec/releases) for the version. Attach the produced docs.

29
spec.md
View File

@ -1,4 +1,5 @@
# Open Container Initiative
## Image Format Specification
This specification defines an OCI Image, consisting of an [image manifest](manifest.md), an [image index](image-index.md) (optional), a set of [filesystem layers](layer.md), and a [configuration](config.md).
@ -9,8 +10,8 @@ The goal of this specification is to enable the creation of interoperable tools
- [Notational Conventions](#notational-conventions)
- [Overview](#overview)
- [Understanding the Specification](#understanding-the-specification)
- [Media Types](media-types.md)
- [Understanding the Specification](#understanding-the-specification)
- [Media Types](media-types.md)
- [Content Descriptors](descriptor.md)
- [Image Layout](image-layout.md)
- [Image Manifest](manifest.md)
@ -20,8 +21,8 @@ The goal of this specification is to enable the creation of interoperable tools
- [Annotations](annotations.md)
- [Conversion](conversion.md)
- [Considerations](considerations.md)
- [Extensibility](considerations.md#extensibility)
- [Canonicalization](considerations.md#canonicalization)
- [Extensibility](considerations.md#extensibility)
- [Canonicalization](considerations.md#canonicalization)
## Notational Conventions
@ -51,19 +52,19 @@ The [OCI Image Media Types](media-types.md) document is a starting point to unde
The high-level components of the spec include:
* [Image Manifest](manifest.md) - a document describing the components that make up a container image
* [Image Index](image-index.md) - an annotated list of manifests
* [Image Layout](image-layout.md) - a filesystem layout representing the contents of an image
* [Filesystem Layer](layer.md) - a changeset that describes a container's filesystem
* [Image Configuration](config.md) - a document determining layer ordering and configuration of the image suitable for translation into a [runtime bundle][runtime-spec]
* [Conversion](conversion.md) - a document describing how this translation should occur
* [Artifacts Guidance](artifacts-guidance.md) - a document describing how to use the spec for packaging content other than OCI images
* [Descriptor](descriptor.md) - a reference that describes the type, metadata and content address of referenced content
- [Image Manifest](manifest.md) - a document describing the components that make up a container image
- [Image Index](image-index.md) - an annotated list of manifests
- [Image Layout](image-layout.md) - a filesystem layout representing the contents of an image
- [Filesystem Layer](layer.md) - a changeset that describes a container's filesystem
- [Image Configuration](config.md) - a document determining layer ordering and configuration of the image suitable for translation into a [runtime bundle][runtime-spec]
- [Conversion](conversion.md) - a document describing how this translation should occur
- [Artifacts Guidance](artifacts-guidance.md) - a document describing how to use the spec for packaging content other than OCI images
- [Descriptor](descriptor.md) - a reference that describes the type, metadata and content address of referenced content
Future versions of this specification may include the following OPTIONAL features:
* Signatures that are based on signing image content address
* Naming that is federated based on DNS and can be delegated
- Signatures that are based on signing image content address
- Naming that is federated based on DNS and can be delegated
[c99-unspecified]: https://www.open-std.org/jtc1/sc22/wg14/www/C99RationaleV5.10.pdf#page=18
[runtime-spec]: https://github.com/opencontainers/runtime-spec