From a2a4db385d47f04161ce8378dbe7c486e22f8453 Mon Sep 17 00:00:00 2001 From: Jon Johnson Date: Thu, 18 Mar 2021 10:38:53 -0700 Subject: [PATCH] Add note about portability concerns --- descriptor.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/descriptor.md b/descriptor.md index aaac73c58..0aa9d5e74 100644 --- a/descriptor.md +++ b/descriptor.md @@ -155,13 +155,16 @@ Note that `[A-F]` MUST NOT be used here. 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 inconsequental, as the majority of time will be spent actually fetching the content. -For very small blobs, the fixed cost will be quite significant. +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 SHOULD NOT populate the `data` field in situations where doing so would unexpectedly modify content identifiers. For example, a registry SHOULD NOT arbitrarily populate `data` fields within uploaded manifests, as that would modify the content address of those manifests. +Implementations SHOULD consider limitations of storage systems when deciding whether or not to embed data. +Many implementations will refuse to accept or parse manifests that violate the limitations of their storage systems, so descriptors concerned with portability SHOULD avoid embedding large amounts of data. + ## Examples The following example describes a [_Manifest_](manifest.md#image-manifest) with a content identifier of "sha256:5b0bcabd1ed22e9fb1310cf6c2dec7cdef19f0ad69efa1f392e94a4333501270" and a size of 7682 bytes: