From a9a16ca3b098d5da350cdca84da8a600b6f5e233 Mon Sep 17 00:00:00 2001 From: James Hewitt Date: Tue, 30 Nov 2021 23:20:40 +0000 Subject: [PATCH 1/2] Use one line per sentence https://github.com/opencontainers/distribution-spec/blob/524a53fd55a76b1b035567c445326c0be0d55676/README.md#markdown-style Signed-off-by: James Hewitt --- spec.md | 175 +++++++++++++++++++++++++++++--------------------------- 1 file changed, 91 insertions(+), 84 deletions(-) diff --git a/spec.md b/spec.md index 3a96ee42..ef0c5bb5 100644 --- a/spec.md +++ b/spec.md @@ -28,8 +28,8 @@ The **Open Container Initiative Distribution Specification** (a.k.a. "OCI Distribution Spec") defines an API protocol to facilitate and standardize the distribution of content. -While OCI Image is the most prominent, the specification is designed to be agnostic of content types. Concepts such as "manifests" and "digests", -are currently defined in the [Open Container Initiative Image Format Specification](https://github.com/opencontainers/image-spec) (a.k.a. "OCI Image Spec"). +While OCI Image is the most prominent, the specification is designed to be agnostic of content types. +Concepts such as "manifests" and "digests", are currently defined in the [Open Container Initiative Image Format Specification](https://github.com/opencontainers/image-spec) (a.k.a. "OCI Image Spec"). To support other artifact types, please see the [Open Container Initiative Artifact Authors Guide](https://github.com/opencontainers/artifacts) (a.k.a. "OCI Artifacts"). @@ -45,8 +45,8 @@ For relevant details and a history leading up to this specification, please see #### Legacy Docker support HTTP headers -Because of the origins this specification, the client MAY encounter Docker-specific headers, such as `Docker-Content-Digest`, -or `Docker-Distribution-API-Version`. These headers are OPTIONAL and clients SHOULD NOT depend on them. +Because of the origins this specification, the client MAY encounter Docker-specific headers, such as `Docker-Content-Digest`, or `Docker-Distribution-API-Version`. +These headers are OPTIONAL and clients SHOULD NOT depend on them. ### Definitions @@ -135,8 +135,10 @@ Typically, the first step in pulling an artifact is to retrieve the manifest. Ho To pull a manifest, perform a `GET` request to a URL in the following form: `/v2//manifests/` [end-3](#endpoints) -`` refers to the namespace of the repository. `` MUST be either (a) the digest of the manifest or (b) a tag. -The `` MUST NOT be in any other format. Throughout this document, `` MUST match the following regular expression: +`` refers to the namespace of the repository. +`` MUST be either (a) the digest of the manifest or (b) a tag. +The `` MUST NOT be in any other format. +Throughout this document, `` MUST match the following regular expression: `[a-z0-9]+([._-][a-z0-9]+)*(/[a-z0-9]+([._-][a-z0-9]+)*)*` @@ -153,11 +155,10 @@ For more information on the use of `Accept` headers and content negotiation, ple A GET request to an existing manifest URL MUST provide the expected manifest, with a response code that MUST be `200 OK`. A successful response SHOULD contain the digest of the uploaded blob in the header `Docker-Content-Digest`. -The `Docker-Content-Digest` header, if present on the response, returns the canonical -digest of the uploaded blob which MAY differ from the provided digest. If the digest does differ, it MAY be the case that -the hashing algorithms used do not match. See [Content Digests](https://github.com/opencontainers/image-spec/blob/v1.0.1/descriptor.md#digests) [apdx-3](#appendix) for information on how to detect the hashing -algorithm in use. Most clients MAY ignore the value, but if it is used, the client MUST verify the value against the uploaded -blob data. +The `Docker-Content-Digest` header, if present on the response, returns the canonical digest of the uploaded blob which MAY differ from the provided digest. +If the digest does differ, it MAY be the case that the hashing algorithms used do not match. +See [Content Digests](https://github.com/opencontainers/image-spec/blob/v1.0.1/descriptor.md#digests) [apdx-3](#appendix) for information on how to detect the hashing algorithm in use. +Most clients MAY ignore the value, but if it is used, the client MUST verify the value against the uploaded blob data. If the manifest is not found in the registry, the response code MUST be `404 Not Found`. @@ -169,8 +170,8 @@ To pull a blob, perform a `GET` request to a URL in the following form: `` is the namespace of the repository, and `` is the blob's digest. A GET request to an existing blob URL MUST provide the expected blob, with a response code that MUST be `200 OK`. -A successful response SHOULD contain the digest of the uploaded blob in the header `Docker-Content-Digest`. If present, -the value of this header MUST be a digest matching that of the response body. +A successful response SHOULD contain the digest of the uploaded blob in the header `Docker-Content-Digest`. +If present, the value of this header MUST be a digest matching that of the response body. If the blob is not found in the registry, the response code MUST be `404 Not Found`. @@ -182,8 +183,8 @@ In order to verify that a repository contains a given manifest or blob, make a ` `/v2//blobs/` [end-2](#endpoints) (for blobs). -A HEAD request to an existing blob or manifest URL MUST return `200 OK`. A successful response SHOULD contain the digest -of the uploaded blob in the header `Docker-Content-Digest`. +A HEAD request to an existing blob or manifest URL MUST return `200 OK`. +A successful response SHOULD contain the digest of the uploaded blob in the header `Docker-Content-Digest`. If the blob or manifest is not found in the registry, the response code MUST be `404 Not Found`. @@ -216,16 +217,19 @@ To obtain a session ID, perform a `POST` request to a URL in the following forma `/v2//blobs/uploads/` [end-4a](#endpoints) -Here, `` refers to the namespace of the repository. Upon success, the response MUST have a code of `202 Accepted`, and MUST include the following header: +Here, `` refers to the namespace of the repository. +Upon success, the response MUST have a code of `202 Accepted`, and MUST include the following header: ``` Location: ``` -The `` MUST contain a UUID representing a unique session ID for the upload to follow. The `` does not necessarily need to be provided by the registry itself. In fact, offloading to another server can be a [better strategy](https://www.backblaze.com/blog/design-thinking-b2-apis-the-hidden-costs-of-s3-compatibility/). +The `` MUST contain a UUID representing a unique session ID for the upload to follow. +The `` does not necessarily need to be provided by the registry itself. +In fact, offloading to another server can be a [better strategy](https://www.backblaze.com/blog/design-thinking-b2-apis-the-hidden-costs-of-s3-compatibility/). -Optionally, the location MAY be absolute (containing the protocol and/or hostname), or it MAY be relative (containing just the URL path). For more information, -see [RFC 7231](https://tools.ietf.org/html/rfc7231#section-7.1.2). +Optionally, the location MAY be absolute (containing the protocol and/or hostname), or it MAY be relative (containing just the URL path). +For more information, see [RFC 7231](https://tools.ietf.org/html/rfc7231#section-7.1.2). Once the `` has been obtained, perform the upload proper by making a `PUT` request to the following URL path, and with the following headers and body: @@ -238,7 +242,9 @@ Content-Type: application/octet-stream ``` -The `` MAY contain critical query parameters. Additionally, it SHOULD match exactly the `` obtained from the `POST` request. It SHOULD NOT be assembled manually by clients except where absolute/relative conversion is necessary. +The `` MAY contain critical query parameters. +Additionally, it SHOULD match exactly the `` obtained from the `POST` request. +It SHOULD NOT be assembled manually by clients except where absolute/relative conversion is necessary. Here, `` is the digest of the blob being uploaded, and `` is its size in bytes. @@ -269,7 +275,8 @@ Content-Type: application/octet-stream Here, `` is the repository's namespace, `` is the blob's digest, and `` is the size (in bytes) of the blob. -The `Content-Length` header MUST match the blob's actual content length. Likewise, the `` MUST match the blob's digest. +The `Content-Length` header MUST match the blob's actual content length. +Likewise, the `` MUST match the blob's digest. Registries that do not support single request monolithic uploads SHOULD return a `202 Accepted` status code and `Location` header and clients SHOULD proceed with a subsequent PUT request, as described by the [POST then PUT upload method](#post-then-put). @@ -279,8 +286,8 @@ Successful completion of the request MUST return a `201 Created` and MUST includ Location: ``` -Here, `` is a pullable blob URL. This location does not necessarily have to be served by your register, for example, in the case of a signed URL from -some cloud storage provider that your registry generates. +Here, `` is a pullable blob URL. +This location does not necessarily have to be served by your registry, for example, in the case of a signed URL from some cloud storage provider that your registry generates. ##### Pushing a blob in chunks @@ -290,7 +297,8 @@ A chunked blob upload is accomplished in three phases: 2. Upload the chunks (`PATCH`) 3. Close the session (`PUT`) -For information on obtaining a session ID, reference the above section on pushing a blob monolithically via the `POST`/`PUT` method. The process remains unchanged for chunked upload, except that the post request MUST include the following header: +For information on obtaining a session ID, reference the above section on pushing a blob monolithically via the `POST`/`PUT` method. +The process remains unchanged for chunked upload, except that the post request MUST include the following header: ``` Content-Length: 0 @@ -313,7 +321,9 @@ Content-Length: The `` refers to the URL obtained from the preceding `POST` request. -The `` refers to the byte range of the chunk, and MUST be inclusive on both ends. The first chunk's range MUST begin with `0`. It MUST match the following regular expression: +The `` refers to the byte range of the chunk, and MUST be inclusive on both ends. +The first chunk's range MUST begin with `0`. +It MUST match the following regular expression: ```regexp ^[0-9]+-[0-9]+$ @@ -329,9 +339,11 @@ Location Each consecutive chunk upload SHOULD use the `` provided in the response to the previous chunk upload. -Chunks MUST be uploaded in order, with the first byte of a chunk being the last chunk's `` plus one. If a chunk is uploaded out of order, the registry MUST respond with a `416 Requested Range Not Satisfiable` code. +Chunks MUST be uploaded in order, with the first byte of a chunk being the last chunk's `` plus one. +If a chunk is uploaded out of order, the registry MUST respond with a `416 Requested Range Not Satisfiable` code. -The final chunk MAY be uploaded using a `PATCH` request or it MAY be uploaded in the closing `PUT` request. Regardless of how the final chunk is uploaded, the session MUST be closed with a `PUT` request. +The final chunk MAY be uploaded using a `PATCH` request or it MAY be uploaded in the closing `PUT` request. +Regardless of how the final chunk is uploaded, the session MUST be closed with a `PUT` request. --- @@ -364,30 +376,27 @@ request in the following format: `/v2//blobs/uploads/?mount=&from=` [end-11](#endpoints). -In this case, `` is the namespace to which the blob will be mounted. `` is the digest of the blob to mount, -and `` is the namespace from which the blob should be mounted. This step is usually taken in place of the -previously-described `POST` request to `/v2//blobs/uploads/` [end-4a](#endpoints) (which is used to initiate an -upload session). +In this case, `` is the namespace to which the blob will be mounted. +`` is the digest of the blob to mount, and `` is the namespace from which the blob should be mounted. +This step is usually taken in place of the previously-described `POST` request to `/v2//blobs/uploads/` [end-4a](#endpoints) (which is used to initiate an upload session). The response to a successful mount MUST be `201 Created`, and MUST contain the following header: ``` Location: ``` -The Location header will contain the registry URL to access the accepted layer file. The Docker-Content-Digest -header returns the canonical digest of the uploaded blob which MAY differ from the provided digest. Most clients MAY -ignore the value but if it is used, the client SHOULD verify the value against the uploaded blob data. +The Location header will contain the registry URL to access the accepted layer file. +The Docker-Content-Digest header returns the canonical digest of the uploaded blob which MAY differ from the provided digest. +Most clients MAY ignore the value but if it is used, the client SHOULD verify the value against the uploaded blob data. The registry MAY treat the `from` parameter as optional, and it MAY cross-mount the blob if it can be found. -Alternatively, if a registry does not support cross-repository mounting or is unable to mount the requested blob, -it SHOULD return a `202`. This indicates that the upload session has begun and that the client MAY proceed with the upload. +Alternatively, if a registry does not support cross-repository mounting or is unable to mount the requested blob, it SHOULD return a `202`. +This indicates that the upload session has begun and that the client MAY proceed with the upload. ##### Pushing Manifests -To push a manifest, perform a `PUT` request to a path in the following format, and with the following headers -and body: -`/v2//manifests/` [end-7](#endpoints) +To push a manifest, perform a `PUT` request to a path in the following format, and with the following headers and body: `/v2//manifests/` [end-7](#endpoints) Clients SHOULD set the `Content-Type` header to the type of the manifest being pushed. All manifests SHOULD include a `mediaType` field declaring the type of the manifest being pushed. @@ -406,9 +415,9 @@ Manifest byte stream: `` is the namespace of the repository, and the `` MUST be either a) a digest or b) a tag. -The uploaded manifest MUST reference any blobs that make up the artifact. However, the list of blobs MAY -be empty. Upon a successful upload, the registry MUST return response code `201 Created`, and MUST have the -following header: +The uploaded manifest MUST reference any blobs that make up the artifact. +However, the list of blobs MAY be empty. +Upon a successful upload, the registry MUST return response code `201 Created`, and MUST have the following header: ``` Location: @@ -416,18 +425,18 @@ Location: The `` is a pullable manifest URL. -An attempt to pull a nonexistent repository MUST return response code `404 Not Found` +An attempt to pull a nonexistent repository MUST return response code `404 Not Found`. #### Content Discovery Currently, the only functionality provided by this workflow is the ability to discover tags. -To fetch the list of tags, perform a `GET` request to a path in the following format: -`/v2//tags/list` [end-8a](#endpoints) +To fetch the list of tags, perform a `GET` request to a path in the following format: `/v2//tags/list` [end-8a](#endpoints) -`` is the namespace of the repository. Assuming a repository is found, this request MUST return a -`200 OK` response code. The list of tags MAY be empty if there are no tags on the repository. If the list is not empty, -the tags MUST be in lexical order (i.e. case-insensitive alphanumeric order). +`` is the namespace of the repository. +Assuming a repository is found, this request MUST return a `200 OK` response code. +The list of tags MAY be empty if there are no tags on the repository. +If the list is not empty, the tags MUST be in lexical order (i.e. case-insensitive alphanumeric order). Upon success, the response MUST be a json body in the following format: ```json @@ -444,55 +453,55 @@ Upon success, the response MUST be a json body in the following format: `` is the namespace of the repository, and ``, ``, and `` are each tags on the repository. In addition to fetching the whole list of tags, a subset of the tags can be fetched by providing the `n` query parameter. -In this case, the path will look like the following: -`/v2//tags/list?n=` [end-8b](#endpoints) +In this case, the path will look like the following: `/v2//tags/list?n=` [end-8b](#endpoints) -`` is the namespace of the repository, and `` is an integer specifying the number of tags requested. The response -to such a request MAY return fewer than `` results, but only when the total number of tags attached to the repository -is less than ``. Otherwise, the response MUST include `` results. When `n` is zero, this endpoint MUST return -an empty list, and MUST NOT include a `Link` header. Without the `last` query parameter (described next), the list returned will -start at the beginning of the list and include `` results. As above, the tags MUST be in lexical order. +`` is the namespace of the repository, and `` is an integer specifying the number of tags requested. +The response to such a request MAY return fewer than `` results, but only when the total number of tags attached to the repository is less than ``. +Otherwise, the response MUST include `` results. +When `n` is zero, this endpoint MUST return an empty list, and MUST NOT include a `Link` header. +Without the `last` query parameter (described next), the list returned will start at the beginning of the list and include `` results. +As above, the tags MUST be in lexical order. -The `last` query parameter provides further means for limiting the number of tags. It is usually used in combination with the -`n` parameter: -`/v2//tags/list?n=&last=` [end-8b](#endpoints) +The `last` query parameter provides further means for limiting the number of tags. +It is usually used in combination with the `n` parameter: `/v2//tags/list?n=&last=` [end-8b](#endpoints) -`` is the namespace of the repository, `` is the number of tags requested, and `` is the *value* of -the last tag. `` MUST NOT be a numerical index, but rather it MUST be a proper tag. A request of this sort will return -up to `` tags, beginning non-inclusively with ``. That is to say, `` will not be included in the -results, but up to `` tags *after* `` will be returned. The tags MUST be in lexical order. +`` is the namespace of the repository, `` is the number of tags requested, and `` is the *value* of the last tag. +`` MUST NOT be a numerical index, but rather it MUST be a proper tag. +A request of this sort will return up to `` tags, beginning non-inclusively with ``. +That is to say, `` will not be included in the results, but up to `` tags *after* `` will be returned. +The tags MUST be in lexical order. When using the `last` query parameter, the `n` parameter is OPTIONAL. #### Content Management -Content management refers to the deletion of blobs, tags, and manifests. Registries MAY implement deletion or they MAY -disable it. Similarly, a registry MAY implement tag deletion, while others MAY allow deletion only by manifest. +Content management refers to the deletion of blobs, tags, and manifests. +Registries MAY implement deletion or they MAY disable it. +Similarly, a registry MAY implement tag deletion, while others MAY allow deletion only by manifest. ##### Deleting tags -`` is the namespace of the repository, and `` is the name of the tag to be deleted. Upon success, the registry -MUST respond with a `202 Accepted` code. If tag deletion is disabled, the registry MUST respond with either a -`400 Bad Request` or a `405 Method Not Allowed`. +`` is the namespace of the repository, and `` is the name of the tag to be deleted. +Upon success, the registry MUST respond with a `202 Accepted` code. +If tag deletion is disabled, the registry MUST respond with either a `400 Bad Request` or a `405 Method Not Allowed`. -To delete a tag, perform a `DELETE` request to a path in the following format: -`/v2//manifests/` [end-9](#endpoints) +To delete a tag, perform a `DELETE` request to a path in the following format: `/v2//manifests/` [end-9](#endpoints) ##### Deleting Manifests -To delete a manifest, perform a `DELETE` request to a path in the following format: -`/v2//manifests/` [end-9](#endpoints) +To delete a manifest, perform a `DELETE` request to a path in the following format: `/v2//manifests/` [end-9](#endpoints) -`` is the namespace of the repository, and `` is the digest of the manifest to be deleted. Upon success, the registry -MUST respond with a `202 Accepted` code. If the repository does not exist, the response MUST return `404 Not Found`. +`` is the namespace of the repository, and `` is the digest of the manifest to be deleted. +Upon success, the registry MUST respond with a `202 Accepted` code. +If the repository does not exist, the response MUST return `404 Not Found`. ##### Deleting Blobs -To delete a blob, perform a `DELETE` request to a path in the following format: -`/v2//blobs/` [end-10](#endpoints) +To delete a blob, perform a `DELETE` request to a path in the following format: `/v2//blobs/` [end-10](#endpoints) -`` is the namespace of the repository, and `` is the digest of the blob to be deleted. Upon success, the -registry MUST respond with code `202 Accepted`. If the blob is not found, a `404 Not Found` code MUST be returned. +`` is the namespace of the repository, and `` is the digest of the blob to be deleted. +Upon success, the registry MUST respond with code `202 Accepted`. +If the blob is not found, a `404 Not Found` code MUST be returned. ### API @@ -500,13 +509,11 @@ The API operates over HTTP. Below is a summary of the endpoints used by the API. #### Determining Support -To check whether or not the registry implements this specification, perform a `GET` request to the following endpoint: -`/v2/` [end-1](#endpoints). +To check whether or not the registry implements this specification, perform a `GET` request to the following endpoint: `/v2/` [end-1](#endpoints). If the response is `200 OK`, then the registry implements this specification. -This endpoint MAY be used for authentication/authorization purposes, but this is out of the purview -of this specification. +This endpoint MAY be used for authentication/authorization purposes, but this is out of the purview of this specification. #### Endpoints @@ -544,9 +551,9 @@ have the following format: } ``` -The `code` field MUST be a unique identifier, containing only uppercase alphabetic characters and underscores. The -`message` field is OPTIONAL, and if present, it SHOULD be a human readable string or MAY be empty. The `detail` field is -OPTIONAL and MAY contain arbitrary JSON data providing information the client can use to resolve the issue. +The `code` field MUST be a unique identifier, containing only uppercase alphabetic characters and underscores. +The `message` field is OPTIONAL, and if present, it SHOULD be a human readable string or MAY be empty. +The `detail` field is OPTIONAL and MAY contain arbitrary JSON data providing information the client can use to resolve the issue. The `code` field MUST be one of the following: From 3c2316eb9ec71117a222f0274fc9e716dd3f892b Mon Sep 17 00:00:00 2001 From: James Hewitt Date: Thu, 25 Nov 2021 11:49:44 +0000 Subject: [PATCH 2/2] Clarifications around manifest reference validation Be more specific for missing references in all manifests and not just image manifests. Signed-off-by: James Hewitt --- spec.md | 45 +++++++++++++++++++++++---------------------- 1 file changed, 23 insertions(+), 22 deletions(-) diff --git a/spec.md b/spec.md index ef0c5bb5..db2faa52 100644 --- a/spec.md +++ b/spec.md @@ -28,8 +28,8 @@ The **Open Container Initiative Distribution Specification** (a.k.a. "OCI Distribution Spec") defines an API protocol to facilitate and standardize the distribution of content. -While OCI Image is the most prominent, the specification is designed to be agnostic of content types. -Concepts such as "manifests" and "digests", are currently defined in the [Open Container Initiative Image Format Specification](https://github.com/opencontainers/image-spec) (a.k.a. "OCI Image Spec"). +The specification is designed to be agnostic of content types. +OCI Image types are currently the most prominent, which are defined in the [Open Container Initiative Image Format Specification](https://github.com/opencontainers/image-spec) (a.k.a. "OCI Image Spec"). To support other artifact types, please see the [Open Container Initiative Artifact Authors Guide](https://github.com/opencontainers/artifacts) (a.k.a. "OCI Artifacts"). @@ -57,7 +57,7 @@ Several terms are used frequently in this document and warrant basic definitions - **Push**: the act of uploading Blobs and Manifests to a Registry - **Pull**: the act of downloading Blobs and Manifests from a Registry - **Blob**: the binary form of content that is stored by a Registry, addressable by a Digest -- **Manifest**: a JSON document which defines an Artifact. Manifests are defined under the OCI Image Spec [apdx-2](#appendix) +- **Manifest**: a JSON document which defines an artifact uploaded via the manifests endpoint. A manifest may reference other blobs in a repository via descriptors. Examples of manifests are defined under the OCI Image Spec [apdx-2](#appendix), such as the image manifest or the image index. - **Config**: a blob referenced in the Manifest which contains Artifact metadata. Config is defined under the OCI Image Spec [apdx-4](#appendix) - **Artifact**: one conceptual piece of content stored as Blobs with an accompanying Manifest containing a Config - **Digest**: a unique identifier created from a cryptographic hash of a Blob's content. Digests are defined under the OCI Image Spec [apdx-3](#appendix) @@ -190,11 +190,12 @@ If the blob or manifest is not found in the registry, the response code MUST be #### Push -Pushing an artifact typically works in the opposite order as a pull: the blobs making up the artifact are uploaded first, -and the manifest last. Strictly speaking, content can be uploaded to the registry in any order, but a registry MAY reject -a manifest if it references blobs that are not yet uploaded, resulting in a `BLOB_UNKNOWN` error [code-1](#error-codes). +Pushing an artifact typically works in the opposite order as a pull: the blobs making up the artifact are uploaded first, and the manifest last. A useful diagram is provided [here](https://github.com/google/go-containerregistry/tree/d7f8d06c87ed209507dd5f2d723267fe35b38a9f/pkg/v1/remote#anatomy-of-an-image-upload). +A registry MAY reject a manifest of any type uploaded to the manifest endpoint if it references manifests or blobs that do not exist in the registry. +When a manifest is rejected for this reason, it must result in one or more `MANIFEST_BLOB_UNKNOWN` errors [code-1](#error-codes). + ##### Pushing blobs There are two ways to push blobs: chunked or monolithic. @@ -557,22 +558,22 @@ The `detail` field is OPTIONAL and MAY contain arbitrary JSON data providing inf The `code` field MUST be one of the following: -| ID | Code | Description | -|-------- | ------------------------|------------------------------------------------| -| code-1 | `BLOB_UNKNOWN` | blob unknown to registry | -| code-2 | `BLOB_UPLOAD_INVALID` | blob upload invalid | -| code-3 | `BLOB_UPLOAD_UNKNOWN` | blob upload unknown to registry | -| code-4 | `DIGEST_INVALID` | provided digest did not match uploaded content | -| code-5 | `MANIFEST_BLOB_UNKNOWN` | blob unknown to registry | -| code-6 | `MANIFEST_INVALID` | manifest invalid | -| code-7 | `MANIFEST_UNKNOWN` | manifest unknown | -| code-8 | `NAME_INVALID` | invalid repository name | -| code-9 | `NAME_UNKNOWN` | repository name not known to registry | -| code-10 | `SIZE_INVALID` | provided length did not match content length | -| code-12 | `UNAUTHORIZED` | authentication required | -| code-13 | `DENIED` | requested access to the resource is denied | -| code-14 | `UNSUPPORTED` | the operation is unsupported | -| code-15 | `TOOMANYREQUESTS` | too many requests | +| ID | Code | Description | +|-------- | ------------------------|------------------------------------------------------------| +| code-1 | `BLOB_UNKNOWN` | blob unknown to registry | +| code-2 | `BLOB_UPLOAD_INVALID` | blob upload invalid | +| code-3 | `BLOB_UPLOAD_UNKNOWN` | blob upload unknown to registry | +| code-4 | `DIGEST_INVALID` | provided digest did not match uploaded content | +| code-5 | `MANIFEST_BLOB_UNKNOWN` | manifest references a manifest or blob unknown to registry | +| code-6 | `MANIFEST_INVALID` | manifest invalid | +| code-7 | `MANIFEST_UNKNOWN` | manifest unknown to registry | +| code-8 | `NAME_INVALID` | invalid repository name | +| code-9 | `NAME_UNKNOWN` | repository name not known to registry | +| code-10 | `SIZE_INVALID` | provided length did not match content length | +| code-12 | `UNAUTHORIZED` | authentication required | +| code-13 | `DENIED` | requested access to the resource is denied | +| code-14 | `UNSUPPORTED` | the operation is unsupported | +| code-15 | `TOOMANYREQUESTS` | too many requests | ### Appendix