Merge pull request #1023 from vbatts/scratch_config

manifest: provide guidance on SCRATCH descriptor (config and layer)

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 = `{}`