From 55292eaac5d57e67af973b758a92f3f5e88de2d9 Mon Sep 17 00:00:00 2001 From: Atlas Kerr Date: Wed, 30 Jan 2019 21:04:37 -0600 Subject: [PATCH 1/2] *:Replace vendor-specific examples. Signed-off-by: Atlas Kerr --- spec.md | 113 ++++++++++++++++++++++++++++++++++---------------------- 1 file changed, 68 insertions(+), 45 deletions(-) diff --git a/spec.md b/spec.md index de89a40d..dbc4ac78 100644 --- a/spec.md +++ b/spec.md @@ -319,19 +319,25 @@ A `404 Not Found` response will be returned if the image is unknown to the regis If the image exists and the response is successful, the image manifest will be returned, with the following format (see [moby/moby#8093](https://github.com/moby/moby/issues/8093) for details): ```json - { - "name": , - "tag": , - "fsLayers": [ - { - "blobSum": - }, - ... - ] - ], - "history": , - "signature": - } +{ + "annotations": { + "com.example.key1": "value1", + "com.example.key2": "value2" + }, + "config": { + "digest": "sha256:6f4e69a5ff18d92e7315e3ee31c62165ebf25bfa05cad05c0d09d8f412dae401", + "mediaType": "application/vnd.oci.image.config.v1+json", + "size": 452 + }, + "layers": [ + { + "digest": "sha256:6f4e69a5ff18d92e7315e3ee31c62165ebf25bfa05cad05c0d09d8f412dae401", + "mediaType": "application/vnd.oci.image.layer.v1.tar+gzip", + "size": 78343 + } + ], + "schemaVersion": 2 +} ``` The client SHOULD verify the returned manifest signature for authenticity before fetching layers. @@ -660,20 +666,25 @@ An image can be pushed using the following request format: PUT /v2//manifests/ Content-Type: - { - "name": , - "tag": , - "fsLayers": [ - { - "blobSum": - }, - ... - ] - ], - "history": , - "signature": , - ... - } + { + "annotations": { + "com.example.key1": "value1", + "com.example.key2": "value2" + }, + "config": { + "digest": "sha256:6f4e69a5ff18d92e7315e3ee31c62165ebf25bfa05cad05c0d09d8f412dae401", + "mediaType": "application/vnd.oci.image.config.v1+json", + "size": 452 + }, + "layers": [ + { + "digest": "sha256:6f4e69a5ff18d92e7315e3ee31c62165ebf25bfa05cad05c0d09d8f412dae401", + "mediaType": "application/vnd.oci.image.layer.v1.tar+gzip", + "size": 78343 + } + ], + "schemaVersion": 2 + } ``` The `name` and `reference` fields of the response body MUST match those specified in the URL. @@ -1450,17 +1461,23 @@ Docker-Content-Digest: Content-Type: { - "name": , - "tag": , - "fsLayers": [ + "annotations": { + "com.example.key1": "value1", + "com.example.key2": "value2" + }, + "config": { + "digest": "sha256:6f4e69a5ff18d92e7315e3ee31c62165ebf25bfa05cad05c0d09d8f412dae401", + "mediaType": "application/vnd.oci.image.config.v1+json", + "size": 452 + }, + "layers": [ { - "blobSum": "" - }, - ... - ] + "digest": "sha256:6f4e69a5ff18d92e7315e3ee31c62165ebf25bfa05cad05c0d09d8f412dae401", + "mediaType": "application/vnd.oci.image.layer.v1.tar+gzip", + "size": 78343 + } ], - "history": , - "signature": + "schemaVersion": 2 } ``` @@ -1645,17 +1662,23 @@ Authorization: Content-Type: { - "name": , - "tag": , - "fsLayers": [ + "annotations": { + "com.example.key1": "value1", + "com.example.key2": "value2" + }, + "config": { + "digest": "sha256:6f4e69a5ff18d92e7315e3ee31c62165ebf25bfa05cad05c0d09d8f412dae401", + "mediaType": "application/vnd.oci.image.config.v1+json", + "size": 452 + }, + "layers": [ { - "blobSum": "" - }, - ... - ] + "digest": "sha256:6f4e69a5ff18d92e7315e3ee31c62165ebf25bfa05cad05c0d09d8f412dae401", + "mediaType": "application/vnd.oci.image.layer.v1.tar+gzip", + "size": 78343 + } ], - "history": , - "signature": + "schemaVersion": 2 } ``` From d93cfa52800990932d24f86fd233070ad9adc5e0 Mon Sep 17 00:00:00 2001 From: Atlas Kerr Date: Wed, 13 Feb 2019 13:48:37 -0600 Subject: [PATCH 2/2] *: Add OCI links to spec. Signed-off-by: Atlas Kerr readme: Fix indenting. Signed-off-by: Atlas Kerr --- spec.md | 82 ++++++++++++++++++++++++++------------------------------- 1 file changed, 37 insertions(+), 45 deletions(-) diff --git a/spec.md b/spec.md index dbc4ac78..7946c847 100644 --- a/spec.md +++ b/spec.md @@ -173,7 +173,7 @@ For detail on individual endpoints, please see the [_Detail_](#detail) section. Actionable failure conditions, covered in detail in their relevant sections, are reported as part of 4xx responses, in a json response body. One or more errors will be returned in the following format: - +```JSON { "errors:" [{ "code": , @@ -183,6 +183,7 @@ One or more errors will be returned in the following format: ... ] } +``` The `code` field will be a unique identifier, all caps with underscores by convention. The `message` field will be a human readable string. @@ -285,16 +286,7 @@ An "image" is a combination of a JSON manifest and individual layer files. The process of pulling an image centers around retrieving these two components. The first step in pulling an image is to retrieve the manifest. -For reference, the relevant manifest fields for the registry are the following: - -| field | description | -|-----------|------------------------------------------------| -| name | The name of the image. | -| tag | The tag for this version of the image. | -| fsLayers | A list of layer descriptors (including digest) | -| signature | A JWS used to verify the manifest content | - -For more information about the manifest format, please see [moby/moby#8093](https://github.com/moby/moby/issues/8093). +For details on manifest formats and their content types, refer to the OCI Image Specification's [manifest property description](https://github.com/opencontainers/image-spec/blob/master/manifest.md#image-manifest-property-descriptions). When the manifest is in hand, the client MUST verify the signature to ensure the names and layers are valid. Once confirmed, the client will then use the digests to download the individual layers. @@ -312,11 +304,10 @@ The `name` and `reference` parameter identify the image and are REQUIRED. The reference MAY include a tag or digest. The client SHOULD include an Accept header indicating which manifest content types it supports. -For more details on the manifest formats and their content types, see [manifest-v2-1.md](https://github.com/docker/distribution/blob/master/docs/spec/manifest-v2-1.md) and [manifest-v2-2.md](https://github.com/docker/distribution/blob/master/docs/spec/manifest-v2-2.md). In a successful response, the Content-Type header will indicate which manifest type is being returned. A `404 Not Found` response will be returned if the image is unknown to the registry. -If the image exists and the response is successful, the image manifest will be returned, with the following format (see [moby/moby#8093](https://github.com/moby/moby/issues/8093) for details): +If the image exists and the response is successful, the image manifest will be returned: ```json { @@ -663,28 +654,28 @@ Once all of the layers for an image are uploaded, the client can upload the imag An image can be pushed using the following request format: ```HTTP - PUT /v2//manifests/ - Content-Type: - - { - "annotations": { - "com.example.key1": "value1", - "com.example.key2": "value2" - }, - "config": { - "digest": "sha256:6f4e69a5ff18d92e7315e3ee31c62165ebf25bfa05cad05c0d09d8f412dae401", - "mediaType": "application/vnd.oci.image.config.v1+json", - "size": 452 - }, - "layers": [ - { - "digest": "sha256:6f4e69a5ff18d92e7315e3ee31c62165ebf25bfa05cad05c0d09d8f412dae401", - "mediaType": "application/vnd.oci.image.layer.v1.tar+gzip", - "size": 78343 - } - ], - "schemaVersion": 2 - } +PUT /v2//manifests/ +Content-Type: + +{ + "annotations": { + "com.example.key1": "value1", + "com.example.key2": "value2" + }, + "config": { + "digest": "sha256:6f4e69a5ff18d92e7315e3ee31c62165ebf25bfa05cad05c0d09d8f412dae401", + "mediaType": "application/vnd.oci.image.config.v1+json", + "size": 452 + }, + "layers": [ + { + "digest": "sha256:6f4e69a5ff18d92e7315e3ee31c62165ebf25bfa05cad05c0d09d8f412dae401", + "mediaType": "application/vnd.oci.image.layer.v1.tar+gzip", + "size": 78343 + } + ], + "schemaVersion": 2 +} ``` The `name` and `reference` fields of the response body MUST match those specified in the URL. @@ -698,7 +689,7 @@ If one or more layers are unknown to the registry, `BLOB_UNKNOWN` errors are ret The `detail` field of the error response will have a `digest` field identifying the missing blob. An error is returned for each unknown blob. The response format is as follows: - +```JSON { "errors:" [{ "code": "BLOB_UNKNOWN", @@ -710,6 +701,7 @@ The response format is as follows: ... ] } +``` ### Listing Repositories @@ -831,16 +823,16 @@ The tags for an image repository can be retrieved with the following request: The response will be in the following format: ```HTTP - 200 OK - Content-Type: application/json +200 OK +Content-Type: application/json - { - "name": , - "tags": [ - , - ... - ] - } +{ + "name": , + "tags": [ + , + ... + ] +} ``` For repositories with a large number of tags, this response MAY be quite large.