Switch from scratch to filler

Signed-off-by: Brandon Mitchell <git@bmitch.net>

manifest.md

@@ -29,7 +29,7 @@ Unlike the [image index](image-index.md), which contains information about a set
 - **`artifactType`** *string*
 
   This OPTIONAL property contains the type of an artifact when the manifest is used for an artifact.
-  This MUST be set when `config.mediaType` is set to the [scratch value](#example-of-a-scratch-config-or-layer-descriptor).
+  This MUST be set when `config.mediaType` is set to the [filler value](#guidance-for-a-filler-descriptor).
   If defined, the value 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].
 
 - **`config`** *[descriptor](descriptor.md)*
@@ -49,16 +49,13 @@ Unlike the [image index](image-index.md), which contains information about a set
 
         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 SCRATCH config and maintain portability the following is considered GUIDANCE.
-    While an empty blob (`size` of 0) may be preferable, practice has shown that not to be ubiquitiously supported.
-    Instead, the blob payload can be the most minimal content that is still valid JSON object: `{}` (`size` of 2).
-    The blob digest of `{}` is `sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a`.
-    See the [example SCRATCH config](#example-of-a-scratch-config-or-layer-descriptor) below, and `ScratchDescriptor` of the reference code.
+    To set an effectively null or empty config and maintain portability see the [guidance for a filler descriptor](#guidance-for-a-filler-descriptor) below, and `FillerDescriptor` 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 a filler descriptor](#guidance-for-a-filler-descriptor) below, and `FillerDescriptor` of the reference code.
 
     When the `config.mediaType` is set to `application/vnd.oci.image.config.v1+json`, the following additional restrictions apply:
 
@@ -67,9 +64,6 @@ Unlike the [image index](image-index.md), which contains information about a set
     - 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.
 
-    For broad portability, if a layer is required to be used, use the SCRATCH layer.
-    See the [example SCRATCH layer](#example-of-a-scratch-config-or-layer-descriptor) below, and `ScratchDescriptor` of the reference code.
-
     Beyond the [descriptor requirements](descriptor.md#properties), the value has the following additional restrictions:
 
     - **`mediaType`** *string*
@@ -89,7 +83,7 @@ Unlike the [image index](image-index.md), which contains information about a set
 
         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)*
 
@@ -144,28 +138,33 @@ Unlike the [image index](image-index.md), which contains information about a set
 }
 ```
 
-## Example of a SCRATCH config or layer descriptor
+## Guidance for a filler descriptor
+
+*Implementers note*: The following is considered GUIDANCE for portability.
 
-Notice that the `mediaType` is subject to the usage or context, while the digest is specifically defined as `ScratchDigestSHA256`.
-When the `ScratchDigestSHA256` is used, the media type SHOULD be set to `application/vnd.oci.scratch.v1+json` to differentiate the descriptor from one pointing to content.
+Parts of the spec necessitate including a descriptor to a blob where some implementations of artifacts do not have associated content.
+While an empty blob (`size` of 0) may be preferable, practice has shown that not to be ubiquitously supported.
+The media type `application/vnd.oci.filler.v1+json` (`MediaTypeFiller`) has been specified for a descriptor that has no content for the implementation.
+The blob payload is the most minimal content that is still valid JSON object: `{}` (`size` of 2).
+The blob digest of `{}` is `sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a`.
 
-```json,title=SCRATCH%20config&mediatype=application/vnd.oci.descriptor.v1%2Bjson
+The resulting descriptor shown here is also defined in reference code as `FillerDescriptor`:
+
+```json,title=filler%20config&mediatype=application/vnd.oci.descriptor.v1%2Bjson
 {
-  "mediaType": "application/vnd.oci.scratch.v1+json",
+  "mediaType": "application/vnd.oci.filler.v1+json",
   "size": 2,
   "digest": "sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a"
 }
 ```
 
-The content of the scratch blob is `{}` (`size` of 2).
-
 ## Guidelines for Artifact Usage
 
 Content other than OCI container images MAY be packaged using the image manifest.
-When this is done, the `config.mediaType` value MUST be set to a value specific to the artifact type or the [scratch value](#example-of-a-scratch-config-or-layer-descriptor).
-If the `config.mediaType` is set to the scratch value, the `artifactType` MUST be defined.
+When this is done, the `config.mediaType` value MUST be set to a value specific to the artifact type or the [filler value](#guidance-for-a-filler-descriptor).
+If the `config.mediaType` is set to the filler value, the `artifactType` MUST be defined.
 If the artifact does not need layers, a single layer SHOULD be included with a non-zero size.
-The suggested content for an unused layer is the [SCRATCH](#example-of-a-scratch-config-or-layer-descriptor) descriptor.
+The suggested content for an unused layer is the [filler descriptor](#guidance-for-a-filler-descriptor).
 
 Here is an example manifest for a typical artifact:
 
@@ -188,15 +187,15 @@ Here is an example manifest for a typical artifact:
 }
 ```
 
-Here is an example manifest for a simple artifact without content in the config, using the scratch descriptor:
+Here is an example manifest for a simple artifact without content in the config, using the filler descriptor:
 
 ```json,title=Artifact%20without%20config&mediatype=application/vnd.oci.image.manifest.v1%2Bjson
 {
   "schemaVersion": 2,
   "mediaType": "application/vnd.oci.image.manifest.v1+json",
   "artifactType": "application/vnd.example+type",
   "config": {
-    "mediaType": "application/vnd.oci.scratch.v1+json",
+    "mediaType": "application/vnd.oci.filler.v1+json",
     "digest": "sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a",
     "size": 2
   },
@@ -210,21 +209,21 @@ Here is an example manifest for a simple artifact without content in the config,
 }
 ```
 
-Here is an example manifest for an artifact with only annotations set, and the content of both blobs set to the scratch descriptor:
+Here is an example manifest for an artifact with only annotations set, and the content of both blobs set to the filler descriptor:
 
 ```json,title=Minimal%20artifact&mediatype=application/vnd.oci.image.manifest.v1%2Bjson
 {
   "schemaVersion": 2,
   "mediaType": "application/vnd.oci.image.manifest.v1+json",
   "artifactType": "application/vnd.example+type",
   "config": {
-    "mediaType": "application/vnd.oci.scratch.v1+json",
+    "mediaType": "application/vnd.oci.filler.v1+json",
     "digest": "sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a",
     "size": 2
   },
   "layers": [
     {
-      "mediaType": "application/vnd.oci.scratch.v1+json",
+      "mediaType": "application/vnd.oci.filler.v1+json",
       "digest": "sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a",
       "size": 2
     }

media-types.md

@@ -10,7 +10,7 @@ The following media types identify the formats described here and their referenc
 - `application/vnd.oci.image.layer.v1.tar`: ["Layer", as a tar archive](layer.md)
 - `application/vnd.oci.image.layer.v1.tar+gzip`: ["Layer", as a tar archive](layer.md#gzip-media-types) compressed with [gzip][rfc1952]
 - `application/vnd.oci.image.layer.v1.tar+zstd`: ["Layer", as a tar archive](layer.md#zstd-media-types) compressed with [zstd][rfc8478]
-- `application/vnd.oci.scratch.v1+json`: [Scratch blob](manifest.md#example-of-a-scratch-config-or-layer-descriptor)
+- `application/vnd.oci.filler.v1+json`: [Filler for unused descriptors](manifest.md#guidance-for-a-filler-descriptor)
 
 The following media types identify a ["Layer" with distribution restrictions](layer.md#non-distributable-layers), but are **deprecated** and not recommended for future use:
 

schema/manifest_test.go

@@ -313,15 +313,15 @@ func TestManifest(t *testing.T) {
 			fail: false,
 		},
 
-		// valid manifest for an artifact using the scratch config and artifactType
+		// valid manifest for an artifact using the filler config and artifactType
 		{
 			manifest: `
 {
   "schemaVersion": 2,
   "mediaType" : "application/vnd.oci.image.manifest.v1+json",
   "artifactType": "application/vnd.example+type",
   "config": {
-    "mediaType": "application/vnd.oci.scratch.v1+json",
+    "mediaType": "application/vnd.oci.filler.v1+json",
     "size": 2,
     "digest": "sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a"
   },

specs-go/v1/manifest.go

@@ -40,9 +40,9 @@ type Manifest struct {
 	Annotations map[string]string `json:"annotations,omitempty"`
 }
 
-// ScratchDescriptor is the descriptor of a blob with content of `{}`.
-var ScratchDescriptor = Descriptor{
-	MediaType: MediaTypeScratch,
+// FillerDescriptor is the descriptor of a blob with content of `{}`.
+var FillerDescriptor = Descriptor{
+	MediaType: MediaTypeFiller,
 	Digest:    `sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a`,
 	Size:      2,
 	Data:      []byte(`{}`),

specs-go/v1/mediatype.go

@@ -70,6 +70,6 @@ const (
 	// MediaTypeImageConfig specifies the media type for the image configuration.
 	MediaTypeImageConfig = "application/vnd.oci.image.config.v1+json"
 
-	// MediaTypeScratch specifies the media type for an unused blob containing the value `{}`
-	MediaTypeScratch = "application/vnd.oci.scratch.v1+json"
+	// MediaTypeFiller specifies the media type for an unused blob containing the value `{}`
+	MediaTypeFiller = "application/vnd.oci.filler.v1+json"
 )