From 5fc84e5f9d4b0a15bf293d44afd9266fededba64 Mon Sep 17 00:00:00 2001 From: Vincent Batts Date: Thu, 20 Oct 2016 16:15:34 -0400 Subject: [PATCH] specs-go: clarify mediatypes Due to the conflicting use of the `mediatType` field across documents, and after discussion on https://github.com/opencontainers/image-spec/pull/411, this changeset removes the use of `mediaType` where it is used to refers to a document's own type. Leaving only the use of `mediaType` for descriptors, where it is used to describe the type of a referenced object. Signed-off-by: Vincent Batts --- image-layout.md | 4 +--- manifest-list.md | 7 ++++--- manifest.md | 6 +++--- schema/image-manifest-schema.json | 8 -------- schema/manifest-list-schema.json | 8 -------- specs-go/v1/config.go | 1 + specs-go/v1/descriptor.go | 5 +++-- specs-go/v1/manifest.go | 2 +- specs-go/v1/manifest_list.go | 3 ++- specs-go/versioned.go | 3 --- 10 files changed, 15 insertions(+), 32 deletions(-) diff --git a/image-layout.md b/image-layout.md index 4151fff84..ea4fa460b 100644 --- a/image-layout.md +++ b/image-layout.md @@ -62,7 +62,7 @@ The blobs directory MAY be missing referenced blobs, in which case the missing b No semantic restriction is given for object names in the `refs` subdirectory. Each object in the `refs` subdirectory MUST be of type `application/vnd.oci.descriptor.v1+json`. -In general the `mediatype` of this [descriptor][descriptors] object will be either `application/vnd.oci.image.manifest.list.v1+json` or `application/vnd.oci.image.manifest.v1+json` although future versions of the spec MAY use a different mediatype. +In general the `mediaType` of this [descriptor][descriptors] object will be either `application/vnd.oci.image.manifest.list.v1+json` or `application/vnd.oci.image.manifest.v1+json` although future versions of the spec MAY use a different mediatype. **Implementor's Note:** A common use case of refs is representing "tags" for a container image. @@ -85,7 +85,6 @@ $ cat ./refs/v1.0 | jq $ cat ./blobs/sha256/e692418e4cbaf90ca69d05a66403747baa33ee08806650b51fab815ad7fc331f | jq { "schemaVersion": 2, - "mediaType": "application/vnd.oci.image.manifest.list.v1+json", "manifests": [ { "mediaType": "application/vnd.oci.image.manifest.v1+json", @@ -103,7 +102,6 @@ $ cat ./blobs/sha256/e692418e4cbaf90ca69d05a66403747baa33ee08806650b51fab815ad7f $ cat ./blobs/sha256/afff3924849e458c5ef237db5f89539274d5e609db5db935ed3959c90f1f2d51 | jq { "schemaVersion": 2, - "mediaType": "application/vnd.oci.image.manifest.v1+json", "config": [ "mediaType": "application/vnd.oci.image.config.v1+json", "size": 7023, diff --git a/manifest-list.md b/manifest-list.md index e16358964..2bb22804f 100644 --- a/manifest-list.md +++ b/manifest-list.md @@ -4,6 +4,7 @@ The manifest list is a higher-level manifest which points to specific [image man While the use of a manifest list is OPTIONAL for image providers, image consumers SHOULD be prepared to process them. This section defines the `application/vnd.oci.image.manifest.list.v1+json` [media type](media-types.md). +For the media type(s) that this document is compatible with, see the [matrix][matrix]. ## *Manifest List* Property Descriptions @@ -14,9 +15,8 @@ This section defines the `application/vnd.oci.image.manifest.list.v1+json` [medi - **`mediaType`** *string* - This REQUIRED property contains the media type of the manifest list. - For this version of the specification, this MUST be set to `application/vnd.oci.image.manifest.list.v1+json`. - For the media type(s) that this is compatible with, see the [matrix](media-types.md#compatibility-matrix). + This property is *reserved* for use, to [maintain compatibility][matrix]. + When used, this field contains the media type of this document, which differs from the [descriptor](descriptor.md#properties) use of `mediaType`. - **`manifests`** *array of objects* @@ -119,3 +119,4 @@ Instead they MUST ignore unknown properties. ``` [runtime-platform2]: https://github.com/opencontainers/runtime-spec/blob/v1.0.0-rc2/config.md#platform +[matrix]: media-types.md#compatibility-matrix diff --git a/manifest.md b/manifest.md index d634e564d..4fa22b658 100644 --- a/manifest.md +++ b/manifest.md @@ -7,6 +7,7 @@ In OCI, this is codified in a [Manifest List](manifest-list.md). The third goal is to be translatable to the [OCI Runtime Specification](https://github.com/opencontainers/runtime-spec). 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 @@ -21,9 +22,8 @@ Unlike the [Manifest List](manifest-list.md), which contains information about a - **`mediaType`** *string* - This REQUIRED property contains the media type of the image manifest. - For this version of the specification, this MUST be set to `application/vnd.oci.image.manifest.v1+json`. - For the media type(s) that this is compatible with see the [matrix](media-types.md#compatibility-matrix). + This property is *reserved* for use, to [maintain compatibility][matrix]. + When used, this field contains the media type of this document, which differs from the [descriptor](descriptor.md#properties) use of `mediaType`. - **`config`** *[descriptor](descriptor.md)* diff --git a/schema/image-manifest-schema.json b/schema/image-manifest-schema.json index 48d3540cb..70f6b734a 100644 --- a/schema/image-manifest-schema.json +++ b/schema/image-manifest-schema.json @@ -11,13 +11,6 @@ "minimum": 2, "maximum": 2 }, - "mediaType": { - "id": "https://opencontainers.org/schema/image/manifest/mediaType", - "type": "string", - "enum": [ - "application/vnd.oci.image.manifest.v1+json" - ] - }, "config": { "$ref": "content-descriptor.json" }, @@ -35,7 +28,6 @@ }, "required": [ "schemaVersion", - "mediaType", "config", "layers" ] diff --git a/schema/manifest-list-schema.json b/schema/manifest-list-schema.json index 990331f8f..5887682c7 100644 --- a/schema/manifest-list-schema.json +++ b/schema/manifest-list-schema.json @@ -11,13 +11,6 @@ "minimum": 2, "maximum": 2 }, - "mediaType": { - "id": "https://opencontainers.org/schema/image/manifest-list/mediaType", - "type": "string", - "enum": [ - "application/vnd.oci.image.manifest.list.v1+json" - ] - }, "manifests": { "type": "array", "items": { @@ -31,7 +24,6 @@ }, "required": [ "schemaVersion", - "mediaType", "manifests" ] } diff --git a/specs-go/v1/config.go b/specs-go/v1/config.go index 894cc6cb7..41feef414 100644 --- a/specs-go/v1/config.go +++ b/specs-go/v1/config.go @@ -78,6 +78,7 @@ type History struct { } // Image is the JSON structure which describes some basic information about the image. +// This provides the `application/vnd.oci.image.config.v1+json` mediatype when marshalled to JSON. type Image struct { // Created defines an ISO-8601 formatted combined date and time at which the image was created. Created string `json:"created,omitempty"` diff --git a/specs-go/v1/descriptor.go b/specs-go/v1/descriptor.go index 83dde9666..7c0264dcb 100644 --- a/specs-go/v1/descriptor.go +++ b/specs-go/v1/descriptor.go @@ -15,9 +15,10 @@ package v1 // Descriptor describes the disposition of targeted content. +// This structure provides `application/vnd.oci.descriptor.v1+json` mediatype when marshalled to JSON type Descriptor struct { - // MediaType contains the MIME type of the referenced object. - MediaType string `json:"mediaType"` + // MediaType is the media type of the object this schema refers to. + MediaType string `json:"mediaType,omitempty"` // Digest is the digest of the targeted content. Digest string `json:"digest"` diff --git a/specs-go/v1/manifest.go b/specs-go/v1/manifest.go index 7d1604379..2b8328861 100644 --- a/specs-go/v1/manifest.go +++ b/specs-go/v1/manifest.go @@ -16,7 +16,7 @@ package v1 import "github.com/opencontainers/image-spec/specs-go" -// Manifest defines a schema2 manifest +// Manifest provides `application/vnd.oci.image.manifest.list.v1+json` mediatype structure when marshalled to JSON. type Manifest struct { specs.Versioned diff --git a/specs-go/v1/manifest_list.go b/specs-go/v1/manifest_list.go index d127ab68a..51d26b0b2 100644 --- a/specs-go/v1/manifest_list.go +++ b/specs-go/v1/manifest_list.go @@ -50,7 +50,8 @@ type ManifestDescriptor struct { Platform Platform `json:"platform"` } -// ManifestList references manifests for various platforms. +// ManifestList references manifests for various platforms. +// This structure provides `application/vnd.oci.image.manifest.list.v1+json` mediatype when marshalled to JSON. type ManifestList struct { specs.Versioned diff --git a/specs-go/versioned.go b/specs-go/versioned.go index d01a1a891..58a1510f3 100644 --- a/specs-go/versioned.go +++ b/specs-go/versioned.go @@ -20,7 +20,4 @@ package specs type Versioned struct { // SchemaVersion is the image manifest schema that this image follows SchemaVersion int `json:"schemaVersion"` - - // MediaType is the media type of this schema. - MediaType string `json:"mediaType"` }