specs-go: clarify mediatypes

Due to the conflicting use of the `mediatType` field across
documents, and after discussion on
opencontainers/image-spec#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 <vbatts@hashbangbash.com>

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,

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

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)*
 

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"
   ]

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"
   ]
 }

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"`

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"`

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
 

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
 

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"`
 }