manifest, specs-go/: provide guidance on SCRATCH config descriptor

Ref: #1025

Through the conversations between artifact manifest and standardizing
the misuse of the image-manifest one of the topics was around when there
is _not_ a `config` needed for the `layers`/blobs.

Since the `config` is a REQUIRED field, it meant setting this to some
valid value.

This guidance intends to set a norm for a blob that need only be pushed
to a registry a single time, and then save on round trips for all future
SCRATCH configs, while also being most widely portability.

to facilitate use by tools that import this reference code to identify
this specific blob when working with an empty/scratch config blob and
layer blob. This will utilize the same blob for both

Signed-off-by: Vincent Batts <[email protected]>

Author: vbatts

manifest.md

@@ -42,6 +42,12 @@ 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 the `ScratchDescriptor()` of the reference code.
+
 - **`layers`** *array of objects*
 
     Each item in the array MUST be a [descriptor](descriptor.md).
@@ -50,6 +56,9 @@ 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 the `ScratchDescriptor()` of the reference code.
+
     Beyond the [descriptor requirements](descriptor.md#properties), the value has the following additional restrictions:
 
     - **`mediaType`** *string*
@@ -122,6 +131,18 @@ Unlike the [image index](image-index.md), which contains information about a set
 }
 ```
 
+## Example of a SCRATCH config or layer descriptor
+
+Notice that the `mediaType` is subject to the usage or context, while the digest is specifically defined as `ScratchDigestSHA256`
+
+```json,title=SCRATCH%20config&mediatype=application/vnd.oci.descriptor.v1%2Bjson
+{
+  "mediaType": "application/vnd.oci.example+json",
+  "size": 2,
+  "digest": "sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a"
+}
+```
+
 [iana]:         https://www.iana.org/assignments/media-types/media-types.xhtml
 [rfc6838]:      https://tools.ietf.org/html/rfc6838
 [rfc6838-s4.2]: https://tools.ietf.org/html/rfc6838#section-4.2

specs-go/v1/manifest.go

@@ -36,3 +36,7 @@ type Manifest struct {
 	// Annotations contains arbitrary metadata for the image manifest.
 	Annotations map[string]string `json:"annotations,omitempty"`
 }
+
+// ScratchDigestSHA256 is the digest of a blob with content of `{}` (size of 2)
+const ScratchDigestSHA256 = `sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a`
+const ScratchDigestData = `{}`