diff --git a/descriptor.md b/descriptor.md index fa6874775..3e287604b 100644 --- a/descriptor.md +++ b/descriptor.md @@ -41,20 +41,20 @@ The following fields contain the primary properties that constitute a Descriptor - **`annotations`** *string-string map* - This OPTIONAL property contains arbitrary metadata for this descriptor. - This OPTIONAL property MUST use the [annotation rules](annotations.md#rules). + This OPTIONAL property contains arbitrary metadata for this descriptor. + This OPTIONAL property MUST use the [annotation rules](annotations.md#rules). -Descriptors pointing to [`application/vnd.oci.image.manifest.v1+json`](manifest.md) SHOULD include the extended field `platform`, see [Image Index Property Descriptions](image-index.md#image-index-property-descriptions) for details. - -### Reserved +- **`data`** *string* -The following field keys are reserved and MUST NOT be used by other specifications. + This OPTIONAL property contains an embedded representation of the referenced content. + Values MUST conform to the Base 64 encoding, as defined in [RFC 4648][rfc4648-s4]. + The decoded data MUST be identical to the referenced content and SHOULD be verified against the [`digest`](#digests) and `size` fields by content consumers. + See [Embedded Content](#embedded-content) for when this is appropriate. -- **`data`** *string* +Descriptors pointing to [`application/vnd.oci.image.manifest.v1+json`](manifest.md) SHOULD include the extended field `platform`, see [Image Index Property Descriptions](image-index.md#image-index-property-descriptions) for details. - This key is RESERVED for future versions of the specification. +### Reserved -All other fields may be included in other OCI specifications. Extended _Descriptor_ field additions proposed in other OCI specifications SHOULD first be considered for addition into this specification. ## Digests @@ -151,6 +151,20 @@ Implementations MAY implement SHA-512 digest verification for use in descriptors When the _algorithm identifier_ is `sha512`, the _encoded_ portion MUST match `/[a-f0-9]{128}/`. Note that `[A-F]` MUST NOT be used here. +## Embedded Content + +In many contexts, such as when downloading content over a network, resolving a descriptor to its content has a measurable fixed "roundtrip" latency cost. +For large blobs, the fixed cost is usually inconsequential, as the majority of time will be spent actually fetching the content. +For very small blobs, the fixed cost can be quite significant. + +Implementations MAY choose to embed small pieces of content directly within a descriptor to avoid roundtrips. + +Implementations MUST NOT populate the `data` field in situations where doing so would modify existing content identifiers. +For example, a registry MUST NOT arbitrarily populate `data` fields within uploaded manifests, as that would modify the content identifier of those manifests. +In contrast, a client MAY populate the `data` field before uploading a manifest, because the manifest would not yet have a content identifier in the registry. + +Implementations SHOULD consider portability when deciding whether to embed data, as some providers are known to refuse to accept or parse manifests that exceed a certain size. + ## Examples The following example describes a [_Manifest_](manifest.md#image-manifest) with a content identifier of "sha256:5b0bcabd1ed22e9fb1310cf6c2dec7cdef19f0ad69efa1f392e94a4333501270" and a size of 7682 bytes: @@ -179,6 +193,7 @@ In the following example, the descriptor indicates that the referenced manifest [rfc3986]: https://tools.ietf.org/html/rfc3986 [rfc4634-s4.1]: https://tools.ietf.org/html/rfc4634#section-4.1 [rfc4634-s4.2]: https://tools.ietf.org/html/rfc4634#section-4.2 +[rfc4648-s4]: https://tools.ietf.org/html/rfc4648#section-4 [rfc6838]: https://tools.ietf.org/html/rfc6838 [rfc6838-s4.2]: https://tools.ietf.org/html/rfc6838#section-4.2 [rfc7230-s2.7]: https://tools.ietf.org/html/rfc7230#section-2.7 diff --git a/specs-go/v1/descriptor.go b/specs-go/v1/descriptor.go index 6e442a085..94f19be62 100644 --- a/specs-go/v1/descriptor.go +++ b/specs-go/v1/descriptor.go @@ -35,6 +35,11 @@ type Descriptor struct { // Annotations contains arbitrary metadata relating to the targeted content. Annotations map[string]string `json:"annotations,omitempty"` + // Data is an embedding of the targeted content. This is encoded as a base64 + // string when marshalled to JSON (automatically, by encoding/json). If + // present, Data can be used directly to avoid fetching the targeted content. + Data []byte `json:"data,omitempty"` + // Platform describes the platform which the image in the manifest runs on. // // This should only be used when referring to a manifest.