Skip to content

Commit

Permalink
manifest: provide guidance on SCRATCH config descriptor
Browse files Browse the repository at this point in the history
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.

Signed-off-by: Vincent Batts <vbatts@hashbangbash.com>
  • Loading branch information
vbatts committed Feb 12, 2023
1 parent e7236d5 commit 4bcc39f
Showing 1 changed file with 16 additions and 0 deletions.
16 changes: 16 additions & 0 deletions manifest.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 a 0 `size` may be preferable, practice has shown that not to be ubiquitious supported.
Instead, the blob payload can be the most minimal content that is still valid JSON: `{}` (size of 2).
The blob digest of `{}` is `sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a`.
See the [example SCRATCH config](#example-of-a-scratch-config-descriptor) below.

- **`layers`** *array of objects*

Each item in the array MUST be a [descriptor](descriptor.md).
Expand Down Expand Up @@ -122,6 +128,16 @@ Unlike the [image index](image-index.md), which contains information about a set
}
```

## Example of a SCRATCH config descriptor

```json,title=SCRATCH%20config&mediatype=application/vnd.oci.descriptor.v1%2Bjson
{
"mediaType": "application/vnd.oci.image.config.v1+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

0 comments on commit 4bcc39f

Please sign in to comment.